> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getvoxai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getvoxai.com/_mcp/server.

# Errors

Every v1 error has the same shape and draws from the same set of codes. Always decide on the `code`, never on the text of the message.

## Response shape

```json
{
  "error": "The request is not valid.",
  "code": "invalid_request",
  "details": [
    { "location": "query", "path": "/limit", "message": "…" }
  ],
  "requestId": "3f0c1f9a-…"
}
```

| Field       | Description                                                                                  |
| ----------- | -------------------------------------------------------------------------------------------- |
| `error`     | A message in English, for a person to read. It can be reworded: do not base decisions on it. |
| `code`      | A stable code, in English and snake_case. This is the contract.                              |
| `details`   | Optional. Depends on the code (see the list below).                                          |
| `requestId` | The same value as the `X-Request-Id` header. Quote it when you write to support.             |

An internal error (`500`) never reveals its cause.

## Statuses

* `400` and `422`: the request must be fixed; repeating it as it is will not help.
* `401` and `403`: a problem with the key, the scope or the plan. See [Authentication](/introduction/authentication).
* `404`: the resource does not exist. A resource of another Organization gives the same `404`.
* `409`: a conflict with the current state of the resource or with a request in progress.
* `429`: too many requests, or a limit of the plan or of the operation. Respect the `Retry-After` header (seconds).
* `5xx`: a temporary problem of the service. Retry with a growing wait. For writes reuse the same `Idempotency-Key`, except for the operations that are not retriable: there read the state of the resource first and follow the **What to do** column. See [Idempotency](/concepts/idempotency).

## When to retry

The **Retry** column of the list below says what to do with each code:

* **Yes**: retry later, respecting `Retry-After` when present.
* **Yes, same key**: retry the same request with the same `Idempotency-Key`, which completes or replays it.
* **No**: retrying the same request gives the same error. Fix the request, or follow "What to do".

Some codes say "Yes" but ask for a **new** `Idempotency-Key` in "What to do" (for example `lines_busy`): follow that, because the same key would not run the request again. A stored error (a `4xx` such as `outside_calling_hours` or `concurrent_modification`) is replayed as it is, and on an operation that is not retriable, such as `POST /calls`, a temporary failure leaves the outcome unknown: the same key gets `409 idempotency_outcome_unknown`.

## Examples

### 422: a request that cannot be carried out

```json
{
  "error": "The destination number is not allowed: only Italian landline and mobile numbers can be called.",
  "code": "destination_not_allowed",
  "requestId": "…"
}
```

Validation errors (`400 invalid_request`) list each problem in `details`, as objects with `location`, `path` and `message`.

### 429: too many requests

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 12
RateLimit-Limit: 600
RateLimit-Remaining: 0
RateLimit-Reset: 12
```

```json
{
  "error": "Too many requests. Retry after the time given by the Retry-After header.",
  "code": "rate_limited",
  "details": { "retryAfterSec": 12 },
  "requestId": "…"
}
```

Wait for the seconds in `Retry-After` (also in `details.retryAfterSec`), then retry.

### 5xx: a temporary problem

```json
{
  "error": "The service is temporarily unavailable. Retry shortly.",
  "code": "service_unavailable",
  "requestId": "…"
}
```

Retry with a growing wait (for example 1, 2, 4, 8 seconds). For a write, reuse the same `Idempotency-Key`; for an operation that is not retriable, read the state of the resource first.

## Codes returned before the route

These codes come from the checks that run before a route is reached, so the routes do not list them.

| Code                         | Status | Retry | What it means                                                                                        | What to do                                                         |
| ---------------------------- | ------ | ----- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `https_required`             | 400    | No    | The request was sent over plain HTTP (production only).                                              | Repeat it with `https://`.                                         |
| `invalid_json`               | 400    | No    | The body is not valid JSON, or its `Content-Encoding` cannot be decoded.                             | Send a valid JSON body, encoded as declared.                       |
| `not_available_in_test_mode` | 403    | No    | The operation cannot run with a test key (`vx_test_`). Today only `POST /v1/caller-requests/export`. | Use a live key (`vx_live_`).                                       |
| `unsupported_media_type`     | 415    | No    | The `Content-Encoding` or the charset of the body is not supported.                                  | Send the body in UTF-8, uncompressed or with a supported encoding. |

The [MCP server](/concepts/mcp-server) adds two codes of its own: `origin_not_allowed` (403, a request coming from a browser) and `method_not_allowed` (405, a method other than `POST`). A tool result can also be the error `upstream_timeout`, which is not an HTTP status: the internal request did not answer within 30 seconds.

## All codes

The list is generated from the API itself: each code appears with the statuses under which a route declares it. The **API Reference** shows, for each route, the codes it declares; the codes returned before the route (above) and the generic ones (`invalid_api_key`, `insufficient_scope`, `rate_limited`, `internal_error`, `service_unavailable`) can come from any route.

### Request errors (4xx)

| Code                                    | Status | Retry         | What it means                                                                                                                                                                                                                                                        | What to do                                                                                                                                                            |
| --------------------------------------- | ------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent_has_no_line`                     | 400    | No            | The agent has no phone line, so it cannot call.                                                                                                                                                                                                                      | Assign a line to the agent in the app.                                                                                                                                |
| `agent_line_not_italian`                | 400    | No            | The phone line of the agent is not an Italian number; outbound calls start only from an Italian line.                                                                                                                                                                | Assign an Italian line to the agent in the app.                                                                                                                       |
| `invalid_api_version`                   | 400    | No            | The `VoxAI-Version` header names a version that does not exist.                                                                                                                                                                                                      | Use one of the versions listed in the `VoxAI-Version` parameter, or omit the header to use the version the key is pinned to.                                          |
| `invalid_cursor`                        | 400    | No            | The `cursor` was not produced by this list, belongs to another filter or order, or is corrupted.                                                                                                                                                                     | Restart from the first page without `cursor`, and pass `next_cursor` back unchanged with the same filters.                                                            |
| `invalid_line`                          | 400    | No            | The `line` filter is not a valid phone number.                                                                                                                                                                                                                       | Pass one of the numbers returned by `GET /lines`, in international format.                                                                                            |
| `invalid_period`                        | 400    | No            | The period is not valid: `from` or `to` with a named period, `custom` without both, a day that does not exist, or `from` after `to`.                                                                                                                                 | Use a named `period`, or `period=custom` with `from` and `to` (YYYY-MM-DD, `to` included).                                                                            |
| `invalid_request`                       | 400    | No            | The path, query or body does not match the schema of the operation: a missing or unknown field, a wrong type, a value out of range.                                                                                                                                  | Fix the request. `details` lists each problem as `{ location, path, message }`: `location` is `params`, `query` or `body` and `path` points to the field.             |
| `invalid_timezone`                      | 400    | No            | The `timezone` is not a known IANA time zone.                                                                                                                                                                                                                        | Use a name such as `Europe/Rome`, or omit it (default `Europe/Rome`).                                                                                                 |
| `not_reindexable`                       | 400    | No            | This document cannot be re-indexed (it has no stored source).                                                                                                                                                                                                        | Delete it and add it again.                                                                                                                                           |
| `period_too_long`                       | 400    | No            | The `custom` period is longer than 13 months.                                                                                                                                                                                                                        | Split the range into shorter periods.                                                                                                                                 |
| `invalid_api_key`                       | 401    | No            | The `Authorization` header is missing, malformed, or carries a key that does not exist, was revoked or has expired.                                                                                                                                                  | Send `Authorization: Bearer vx_live_…` (or `vx_test_…`) with an active key. Create a new key in the app if this one expired.                                          |
| `feature_not_available`                 | 403    | No            | The plan of the organization does not include the API, or the feature this operation needs.                                                                                                                                                                          | Upgrade the plan in the app. Reads and deletions stay available after a downgrade.                                                                                    |
| `insufficient_scope`                    | 403    | No            | The key does not have the scope this operation requires (written in the description of the operation).                                                                                                                                                               | Create a key with the required scope (an Owner or Admin can do it in the app), or ask for the scope to be added.                                                      |
| `ip_not_allowed`                        | 403    | No            | The key has an IP allow-list and the request comes from an address that is not on it.                                                                                                                                                                                | Call from an allowed address, or add this address to the key in the app.                                                                                              |
| `organization_suspended`                | 403    | No            | The organization that owns the key is suspended.                                                                                                                                                                                                                     | Contact the organization Owner: nothing can be done through the API until the organization is active again.                                                           |
| `quota_exhausted`                       | 403    | No            | The minutes included in the plan are used up and the organization does not allow extra minutes.                                                                                                                                                                      | Buy a top-up pack or upgrade the plan in the app.                                                                                                                     |
| `webhook_endpoint_disabled_by_platform` | 403    | No            | The endpoint was disabled by VoxAI staff (`disabled_reason: platform`), so it cannot be reactivated through the API.                                                                                                                                                 | Contact support.                                                                                                                                                      |
| `closure_not_found`                     | 404    | No            | The agent has no closure with this id.                                                                                                                                                                                                                               | Check the id with `GET /agents/{agent_id}/closures`.                                                                                                                  |
| `not_found`                             | 404    | No            | The resource does not exist, or it belongs to another organization: the two cases give the same answer on purpose.                                                                                                                                                   | Check the id. Ids come from the list operations of the same organization.                                                                                             |
| `variable_not_found`                    | 404    | No            | The agent has no variable with this name.                                                                                                                                                                                                                            | Check the name with `GET /agents/{agent_id}/variables`.                                                                                                               |
| `agent_configuration_unreadable`        | 409    | No            | The configuration of the agent cannot be read, so it cannot be changed safely.                                                                                                                                                                                       | Contact support with the `requestId`.                                                                                                                                 |
| `agent_suspended`                       | 409    | No            | The agent is suspended.                                                                                                                                                                                                                                              | Resume it with `POST /agents/{agent_id}/resume`, then retry.                                                                                                          |
| `already_exists`                        | 409    | No            | The same document is already in the knowledge base: the same file with the same name, or the same address.                                                                                                                                                           | For an address, re-index the existing document instead of adding it again. For a file, nothing to do.                                                                 |
| `caller_has_active_call`                | 409    | Yes, same key | A call with this number is in progress: data cannot be erased while it is being written.                                                                                                                                                                             | Retry in a minute, with the same `Idempotency-Key`.                                                                                                                   |
| `caller_request_in_progress`            | 409    | Yes           | Another erasure request for the same number is running.                                                                                                                                                                                                              | Retry in a minute. If the other request completed, the data is already erased.                                                                                        |
| `concurrent_modification`               | 409    | Yes           | The resource (an agent or a webhook endpoint) was changed by someone else between the read and the write.                                                                                                                                                            | Read the resource again and retry with a new `Idempotency-Key`.                                                                                                       |
| `duplicate_content`                     | 409    | No            | A file with the same content is already in the knowledge base, under another name. Nothing was added.                                                                                                                                                                | Nothing to do: the existing document already holds this content. To keep it under the new name, delete the existing one first.                                        |
| `idempotency_outcome_unknown`           | 409    | No            | A previous request with this `Idempotency-Key` failed with a `429`, a `5xx` or a temporary `409` inside a NOT retriable operation, or was interrupted with no response, so its outcome is not known and it is never run again with the same key.                     | Read the state of the resource (for example `GET /outbound-calls/{outbound_call_id}` or the list) and retry with a NEW key only if the operation did not happen.      |
| `invalid_campaign_state`                | 409    | No            | The campaign is not in a state that allows this operation (for example pausing a campaign that is not running).                                                                                                                                                      | Read the campaign and check its `status` before retrying.                                                                                                             |
| `license_not_active`                    | 409    | No            | The organization has no active plan (for example it expired).                                                                                                                                                                                                        | Renew the plan in the app.                                                                                                                                            |
| `name_conflict`                         | 409    | No            | A document with the same name already exists.                                                                                                                                                                                                                        | Use another name, or delete the existing document first.                                                                                                              |
| `request_in_progress`                   | 409    | Yes, same key | A request with the same `Idempotency-Key` is still running.                                                                                                                                                                                                          | Wait a few seconds and retry with the same key: you will get the outcome of the first request.                                                                        |
| `source_unavailable`                    | 409    | No            | The original file of the document is no longer stored, so it cannot be read again.                                                                                                                                                                                   | Delete the document and upload the file again.                                                                                                                        |
| `too_many_closures`                     | 409    | No            | The agent already has the maximum number of upcoming closures (`details.limit`, 50).                                                                                                                                                                                 | Delete a closure first.                                                                                                                                               |
| `too_many_variables`                    | 409    | No            | The agent already has the maximum number of variables (`details.limit`, 30).                                                                                                                                                                                         | Delete a variable first.                                                                                                                                              |
| `too_many_webhook_endpoints`            | 409    | No            | The organization reached the maximum number of webhook endpoints.                                                                                                                                                                                                    | Delete an endpoint before creating another.                                                                                                                           |
| `variable_in_use`                       | 409    | No            | An active campaign of the agent needs this variable.                                                                                                                                                                                                                 | Pause or complete the campaigns in `details.campaigns`, then retry.                                                                                                   |
| `variable_not_static`                   | 409    | No            | The variable gets its value from the call or from a campaign, not from a fixed value: it cannot be changed here.                                                                                                                                                     | Change it in the app, or use a different name for a fixed value.                                                                                                      |
| `webhook_delivery_expired`              | 409    | No            | The body of the delivery was deleted 7 days after its outcome, so it cannot be resent.                                                                                                                                                                               | Nothing to resend: the event is no longer kept.                                                                                                                       |
| `webhook_endpoint_inactive`             | 409    | No            | The endpoint is paused or disabled.                                                                                                                                                                                                                                  | Reactivate it with `PATCH /webhook-endpoints/{endpoint_id}` and `status: active`, unless it was disabled by VoxAI staff (`disabled_reason: platform`).                |
| `payload_too_large`                     | 413    | No            | The request body is larger than the limit of the operation.                                                                                                                                                                                                          | Send a smaller body: for documents, a smaller file (at most 20 MB).                                                                                                   |
| `caller_export_too_large`               | 422    | No            | This number has more calls than an immediate export can hold (200).                                                                                                                                                                                                  | Contact support with the `requestId` to receive the export by other means.                                                                                            |
| `campaign_contacts_limit_reached`       | 422    | No            | The campaign would go over the maximum number of contacts (`details.limit`).                                                                                                                                                                                         | Send fewer contacts, or create another campaign.                                                                                                                      |
| `contact_origin_invalid`                | 422    | No            | `contact_origin` is present but not valid: `basis` or `purpose` missing or unknown, `reference` longer than 120 characters, `opposition_register_checked_on` not a valid date, in the future, or missing when `purpose` is `marketing` and `basis` is not `consent`. | Fix the fields in `details`: each item is `{ field, code }`, with `code` one of `missing`, `invalid`, `unknown_value`, `too_long`, `in_the_future`, `invalid_format`. |
| `contact_origin_required`               | 422    | No            | The body has no `contact_origin` at all.                                                                                                                                                                                                                             | Declare where the right to call comes from in `contact_origin` (see the field description).                                                                           |
| `destination_not_allowed`               | 422    | No            | `to` is not an Italian landline, mobile or toll-free (800, 803) number (international, premium-rate, short and emergency numbers are refused).                                                                                                                       | Call only Italian landline, mobile or toll-free (800, 803) numbers, in E.164 format (`+39…`).                                                                         |
| `destination_objected`                  | 422    | No            | The number is on the do-not-call list of the organization (it objected to being called).                                                                                                                                                                             | Do not call this number. Only the person can withdraw the objection (`POST /caller-requests/objections/withdraw`).                                                    |
| `idempotency_key_reused`                | 422    | No            | The same `Idempotency-Key` was already used in the last 24 hours with a different request (other operation, path or body).                                                                                                                                           | Use a new key for a new request. Reuse a key only to repeat exactly the same request.                                                                                 |
| `invalid_contacts`                      | 422    | No            | At least one contact of the block is not valid; the whole block was rejected and nothing was added.                                                                                                                                                                  | Fix the rows listed in `details` (each with its index) and send the block again.                                                                                      |
| `invalid_webhook_url`                   | 422    | No            | The URL is not a public `https` address, or it contains credentials or a fragment (`details.reason`).                                                                                                                                                                | Use a public `https` URL without user, password or `#fragment`.                                                                                                       |
| `knowledge_storage_full`                | 422    | No            | The knowledge base of the organization has reached its storage limit.                                                                                                                                                                                                | Delete documents you no longer need, then retry.                                                                                                                      |
| `missing_variables`                     | 422    | No            | The agent declares required variables that are not in `variables`.                                                                                                                                                                                                   | Send the variables listed in `details.names` (see `GET /agents/{agent_id}/variables`).                                                                                |
| `outside_calling_hours`                 | 422    | Yes           | Now is outside the calling hours of the organization for outbound calls.                                                                                                                                                                                             | Retry at the time in `details.next_window_start` with a NEW `Idempotency-Key`. When it is `null`, the calling hours leave no window open: check them in the app.      |
| `phone_confirmation_mismatch`           | 422    | No            | `confirm_phone_number` does not repeat `phone_number` exactly. Nothing was erased.                                                                                                                                                                                   | Send the same number in both fields.                                                                                                                                  |
| `too_many_records`                      | 422    | No            | Too many records were found for this number, so the operation was stopped for safety.                                                                                                                                                                                | Contact support with the `requestId`: the request will be handled by hand.                                                                                            |
| `unknown_event_type`                    | 422    | No            | One of the event types does not exist, or is reserved and not emitted yet.                                                                                                                                                                                           | Use the names in `details.event_types` (see `GET /webhook-event-types`).                                                                                              |
| `daily_outbound_limit_reached`          | 429    | Yes           | The organization reached its daily limit of outbound calls.                                                                                                                                                                                                          | Retry after the seconds in the `Retry-After` header (the next day), with a NEW `Idempotency-Key`.                                                                     |
| `lines_busy`                            | 429    | Yes           | All the concurrent-call lines of the plan are in use.                                                                                                                                                                                                                | Retry after the seconds in the `Retry-After` header, with a NEW `Idempotency-Key`.                                                                                    |
| `rate_limited`                          | 429    | Yes           | Too many requests: over the per-minute limit of this key or of the whole organization (see `rate_limits` in `GET /me`), or over a limit of the operation itself, such as the hourly limit on webhook tests and resends.                                              | Wait for the number of seconds in the `Retry-After` header, then retry. Spread requests over time.                                                                    |

### Service errors (5xx)

| Code                             | Status | Retry         | What it means                                                                                                     | What to do                                                                                                                                                                                                                                                                                                                     |
| -------------------------------- | ------ | ------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `caller_erasure_incomplete`      | 500    | Yes, same key | The erasure stopped halfway: part of the data may already be gone.                                                | Retry the same request with the same `Idempotency-Key`: it completes the erasure.                                                                                                                                                                                                                                              |
| `internal_error`                 | 500    | Yes           | An unexpected error on our side.                                                                                  | Retry once after a few seconds. For writes marked as retriable, retry with the same `Idempotency-Key`, so the operation is never done twice; for the other writes, first read the state of the resource, then retry with a NEW key only if the operation did not happen. If it persists, contact support with the `requestId`. |
| `telephony_unavailable`          | 502    | Yes           | The telephone network did not accept the call. Nothing was dialed.                                                | Retry after a few seconds with a NEW `Idempotency-Key`.                                                                                                                                                                                                                                                                        |
| `api_not_configured`             | 503    | No            | The API is not enabled on this service.                                                                           | Contact support.                                                                                                                                                                                                                                                                                                               |
| `knowledge_indexing_unavailable` | 503    | Yes           | Indexing is not available on the service right now, so no document can be added or re-indexed. Nothing was saved. | Retry later. For a re-index, retry with a NEW `Idempotency-Key`. If it persists, contact support with the `requestId`.                                                                                                                                                                                                         |
| `service_unavailable`            | 503    | Yes           | A component the operation depends on is temporarily unavailable.                                                  | Retry after a few seconds. For writes marked as retriable, use the same `Idempotency-Key`; for the other writes, first read the state of the resource, then retry with a NEW key only if the operation did not happen.                                                                                                         |
| `webhook_internal_error`         | 503    | Yes           | The delivery could not be signed because of a problem on our side. Nothing was sent.                              | Retry later; if it persists, rotate the signing secret.                                                                                                                                                                                                                                                                        |
| `webhook_send_not_recorded`      | 503    | Yes           | The request was sent but its outcome could not be recorded.                                                       | Your server may have received it: deduplicate on the `VoxAI-Event-Id` header. Retry shortly if needed.                                                                                                                                                                                                                         |
| `webhooks_not_configured`        | 503    | No            | Webhooks are not enabled on this service.                                                                         | Contact support.                                                                                                                                                                                                                                                                                                               |