CloudTalk API HTTP Error Codes: Causes and Resolutions

The CloudTalk REST API (v1.7) signals the outcome of every request through standard HTTP status codes. Successful responses carry 2xx codes, client errors carry 4xx codes, and server-side failures carry 5xx codes. For any error on the core API, the response body follows the standard error envelope so you can inspect the machine-readable status field and the human-readable message field in a single, consistent place. The other surfaces use different error shapes — see the note below. This reference covers the codes you may encounter, explains what causes them, and tells you what to do about each.

Dialer, VoiceAgent and Conversation Intelligence return a different error envelope. Service-raised errors use

{ "statusCode": 400, "message": "Validation error", "error": "Bad Request", "correlationId": "YevPQs", "subErrors": ["incorrect email"] }

— subErrors is present on validation failures only. Quote the correlationId when contacting support.401 is the exception on those surfaces. It is answered by the authentication layer in front of api.cloudtalk.io, before the request reaches the service, so it returns { "code": "UNAUTHORIZED", "message": "You are not authorized to access this resource." } instead. Handle both shapes in your error parser.

Error Envelope Format

When a request fails, the API returns an error envelope in the response body regardless of the HTTP status code:

Error envelope structure

{
  "responseData": {
    "status": 404,
    "message": "Not Found"
  }
}

Both fields are always present on error responses. The status field mirrors the HTTP status code of the response, and message contains a brief description you can log or surface to users. For full envelope documentation, see the Response Envelopes guide.

Status Code Reference

2xx — Success

Code	Name	Meaning
`200`	OK	The request succeeded. Most `200` responses carry the requested resource or collection, but not all — Make a call returns only `{"responseData": {"status": 200}}`. Check the endpoint’s documented response schema.
`201`	Created	A new resource was created. Returned by the core API’s `PUT` create endpoints (`PUT /contacts/add.json`) and by the Dialer’s `POST` creates (`POST /dialer/campaigns`).
`202`	Accepted	The request was accepted for asynchronous processing. Returned when you queue a Dialer export job; poll the returned `jobId` for the result.
`204`	No Content	The request succeeded and there is no response body. Returned by the VoiceAgent initiate endpoint and by Dialer delete operations.

4xx — Client Errors

Code	Name	Meaning
`400`	Bad Request	The request body or query parameters are malformed or contain invalid values.
`401`	Unauthorized	API credentials are missing, malformed, or do not match any active key pair.
`403`	Forbidden	Your credentials are valid but the action is not permitted — e.g. the target agent is not online, or your account has insufficient funds.
`404`	Not Found	The requested resource does not exist or has never existed.
`406`	Not Acceptable	Input validation failed — a required field is missing, a value is out of range, or a field has the wrong type.
`409`	Conflict	The request conflicts with the current state of a resource — e.g. an agent is already in a call and cannot be called again.
`410`	Gone	The resource existed but is no longer available — e.g. a call recording that has been deleted or has passed its retention period.
`422`	Unprocessable Entity	The request was well-formed but could not be processed — e.g. a Dialer campaign update that conflicts with the campaign’s current configuration. Returned by Dialer and VoiceAgent operations.
`424`	Failed Dependency	A prerequisite was not met — e.g. the CueCard endpoint requires an active call on the target agent’s line.
`429`	Too Many Requests	You have exceeded the rate limit — 60 requests per minute per company on the core API. Dialer has its own dedicated per-company budget and returns `429` against that instead. See the Rate Limiting guide.

5xx — Server Errors

Code	Name	Meaning
`500`	Internal Server Error	An unexpected error occurred on the CloudTalk servers. The request was valid but the server could not process it.
`503`	Service Unavailable	A downstream service is temporarily unavailable. Retry with backoff. Documented on Dialer and VoiceAgent operations.

Example Error Envelopes

The following are representative core API error bodies. The status field always mirrors the HTTP status code; the message wording is set per endpoint, so check the endpoint’s reference page for its exact string.

{
  "responseData": {
    "status": 401,
    "message": "Unauthorized"
  }
}

{
  "responseData": {
    "status": 404,
    "message": "Not found."
  }
}

{
  "responseData": {
    "status": 406,
    "message": "Invalid input data."
  }
}

{
  "responseData": {
    "status": 429,
    "message": "Too Many Requests"
  }
}

{
  "responseData": {
    "status": 500,
    "message": "Something went wrong."
  }
}

Troubleshooting by Error Code

400 Bad Request

Inspect your request body and query string carefully. Common causes include sending a numeric value as a string, omitting a required field, or passing a date in an unexpected format. Date and time values are UTC, but the exact form differs per endpoint — the date_from / date_to filters on call history take 2017-12-24 12:22:00, while call record fields come back as 2017-10-04T06:33:37.000Z. Validate your payload against the endpoint’s parameter reference before retrying.

401 Unauthorized

Verify that you are passing credentials using HTTP Basic Auth with KEY_ID as the username and KEY_SECRET as the password. Check that the key pair is active in the CloudTalk dashboard and has not been revoked. Ensure you are not accidentally including extra whitespace or newline characters in the credentials.

cURL — correct Basic Auth syntax

curl -u YOUR_KEY_ID:YOUR_KEY_SECRET \
  -H "Accept: application/json" \
  'https://my.cloudtalk.io/api/calls/index.json'

403 Forbidden

Your credentials are valid, but the operation is not allowed in the current context. The API documents three causes: the target agent is not online (Make a call), the account has insufficient funds (Send sms), and the account has reached its maximum number of agents (Add an agent). Check the agent’s status and your account balance in the CloudTalk dashboard.

404 Not Found

The resource ID you provided does not match any record in the system. Double-check that you are using the correct numeric ID (not a name or slug), and that you are calling the right base URL — a valid path on the wrong host returns 404. Also confirm the record belongs to the CloudTalk project your credentials target; IDs are scoped to a project.

406 Not Acceptable

Input validation failed on one or more fields. Review the endpoint’s parameter definitions, ensure all required fields are present, and check that values fall within the documented constraints (e.g. limit must be between 1 and 1000). Some endpoints return additional context in the message field naming the offending parameter.

409 Conflict

The operation cannot proceed because of the resource’s current state. For example, you cannot initiate a second call to an agent who already has an active call. Poll the agent’s status before retrying.

410 Gone

The resource existed previously but has since been deleted or has expired. The API documents this on call recordings — Recording expired. or Recording not found. — which are subject to your account’s data-retention policy. A recording in this state is not retrievable through the API; remove the reference from your system and avoid requesting it again.

424 Failed Dependency

A required precondition was not met. The CueCard endpoint, for instance, requires the target agent to have an active call in progress. Verify the prerequisite state before calling the endpoint.

422 Unprocessable Entity

The request parsed correctly but could not be applied — typically a Dialer or VoiceAgent operation that conflicts with the current state of the target resource, or a field combination the service rejects. Read message and, where present, subErrors for the field-level detail, then adjust the payload rather than retrying it unchanged.

429 Too Many Requests

You have exceeded 60 requests per minute. Read the X-CloudTalkAPI-ResetTime response header, sleep until that Unix timestamp, then retry. Implement exponential backoff in your client to avoid sustained bursts. See the Rate Limiting guide for a complete retry implementation.

500 Internal Server Error

The error is on CloudTalk’s side. Wait a few seconds and retry the request — transient 500 errors often resolve on the next attempt. If the error persists for more than a few minutes, check the CloudTalk Status Page and contact support if no incident is listed.

503 Service Unavailable

A service the request depends on is temporarily unavailable. Retry with exponential backoff, exactly as you would for a 429 but without a reset timestamp to aim at. If it persists, check the CloudTalk Status Page.

Errors on api.cloudtalk.io

Conversation Intelligence, VoiceAgent and Dialer all sit behind https://api.cloudtalk.io/v1 and do not use the responseData error envelope. They return errors as direct top-level JSON objects, in one of two shapes. 401 Unauthorized is answered by the authentication layer in front of the service, before your request reaches it. It is the same body on every endpoint of this host:

401 — from the auth layer

{
  "code": "UNAUTHORIZED",
  "message": "You are not authorized to access this resource."
}

Every other error on that host is documented with the fuller shape. subErrors appears on validation failures; correlationId is always present, and support will ask for it:

400 — from the service

{
  "statusCode": 400,
  "message": "Validation error",
  "error": "Bad Request",
  "correlationId": "YevPQs",
  "subErrors": ["incorrect email"]
}

Handle both in a separate error-parsing path from your core API handler: branch on the presence of code versus statusCode, never on responseData.

Get call details, served by analytics-api.cloudtalk.io, uses a third variant — { "statusCode", "message", "error" } with no correlationId, and message may be an array of validation strings.

Quick Reference Card

Check your credentials (401)

Confirm your KEY_ID and KEY_SECRET are correct, active, and passed via HTTP Basic Auth.

Validate your input (400 / 406)

Cross-reference the request body against the endpoint’s parameter docs and ensure all required fields are present and correctly typed.

Back off and retry (429)

Sleep until X-CloudTalkAPI-ResetTime and retry with exponential backoff. Consider caching to reduce request volume.

Contact support (500)

Persistent 500 errors indicate a platform issue. Check the status page and open a support ticket with the request timestamp and endpoint URL.

Getting Started

API Concepts

Changelog

CloudTalk API HTTP Error Codes: Causes and Resolutions

Error Envelope Format

Status Code Reference

2xx — Success

4xx — Client Errors

5xx — Server Errors

Example Error Envelopes

Troubleshooting by Error Code

Errors on api.cloudtalk.io

Quick Reference Card

Check your credentials (401)

Validate your input (400 / 406)

Back off and retry (429)

Contact support (500)

​Error Envelope Format

​Status Code Reference

​2xx — Success

​4xx — Client Errors

​5xx — Server Errors

​Example Error Envelopes

​Troubleshooting by Error Code

​Errors on api.cloudtalk.io

​Quick Reference Card

Check your credentials (401)

Validate your input (400 / 406)

Back off and retry (429)

Contact support (500)

Error Envelope Format

Status Code Reference

2xx — Success

4xx — Client Errors

5xx — Server Errors

Example Error Envelopes

Troubleshooting by Error Code

Errors on api.cloudtalk.io

Quick Reference Card