> ## Documentation Index
> Fetch the complete documentation index at: https://developers.cloudtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.
# CloudTalk API HTTP Error Codes: Causes and Resolutions
> Reference for the HTTP status codes returned by the CloudTalk API, with common causes and recommended fixes for 4xx and 5xx errors, plus the error body shapes each surface uses.
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:
```json Error envelope structure theme={"system"}
{
"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](/guides/response-envelopes).
***
## 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](/api-reference/calls/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](/guides/rate-limiting). |
***
### 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.
```json 401 Unauthorized theme={"system"}
{
"responseData": {
"status": 401,
"message": "Unauthorized"
}
}
```
```json 404 Not Found theme={"system"}
{
"responseData": {
"status": 404,
"message": "Not found."
}
}
```
```json 406 Not Acceptable theme={"system"}
{
"responseData": {
"status": 406,
"message": "Invalid input data."
}
}
```
```json 429 Too Many Requests theme={"system"}
{
"responseData": {
"status": 429,
"message": "Too Many Requests"
}
}
```
```json 500 Internal Server Error theme={"system"}
{
"responseData": {
"status": 500,
"message": "Something went wrong."
}
}
```
***
## Troubleshooting by Error Code
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.
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.
```bash cURL — correct Basic Auth syntax theme={"system"}
curl -u YOUR_KEY_ID:YOUR_KEY_SECRET \
-H "Accept: application/json" \
'https://my.cloudtalk.io/api/calls/index.json'
```
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](/api-reference/calls/make-a-call)), the account has insufficient funds ([Send sms](/api-reference/sms/send-sms)), and the account has reached its maximum number of agents ([Add an agent](/api-reference/agents/add-an-agent)). Check the agent's status and your account balance in the CloudTalk dashboard.
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.
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.
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.
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.
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.
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.
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](/guides/rate-limiting) for a complete retry implementation.
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](https://status.cloudtalk.io/) and contact support if no incident is listed.
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](https://status.cloudtalk.io/).
***
## 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:
```json 401 — from the auth layer theme={"system"}
{
"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:
```json 400 — from the service theme={"system"}
{
"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](/api-reference/calls/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
Confirm your `KEY_ID` and `KEY_SECRET` are correct, active, and passed via HTTP Basic Auth.
Cross-reference the request body against the endpoint's parameter docs and ensure all required fields are present and correctly typed.
Sleep until `X-CloudTalkAPI-ResetTime` and retry with exponential backoff. Consider caching to reduce request volume.
Persistent `500` errors indicate a platform issue. Check the status page and open a support ticket with the request timestamp and endpoint URL.
## Related topics
- [CloudTalk API Response Envelope Formats and Schema](/guides/response-envelopes.md)
- [How to Authenticate Requests to the CloudTalk REST API](/guides/authentication.md)
- [CloudTalk REST API v1.7 — Complete Developer Reference](/api-reference/overview.md)