Skip to navigation

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

{
"error": "The request is not valid.",
"code": "invalid_request",
"details": [
{ "location": "query", "path": "/limit", "message": "…" }
],
"requestId": "3f0c1f9a-…"
}
FieldDescription
errorA message in English, for a person to read. It can be reworded: do not base decisions on it.
codeA stable code, in English and snake_case. This is the contract.
detailsOptional. Depends on the code (see the list below).
requestIdThe 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.
  • 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.

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

{
"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/1.1 429 Too Many Requests
Retry-After: 12
RateLimit-Limit: 600
RateLimit-Remaining: 0
RateLimit-Reset: 12
{
"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

{
"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.

CodeStatusRetryWhat it meansWhat to do
https_required400NoThe request was sent over plain HTTP (production only).Repeat it with https://.
invalid_json400NoThe body is not valid JSON, or its Content-Encoding cannot be decoded.Send a valid JSON body, encoded as declared.
not_available_in_test_mode403NoThe operation cannot run with a test key (vx_test_). Today only POST /v1/caller-requests/export.Use a live key (vx_live_).
unsupported_media_type415NoThe 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 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)

CodeStatusRetryWhat it meansWhat to do
agent_has_no_line400NoThe agent has no phone line, so it cannot call.Assign a line to the agent in the app.
agent_line_not_italian400NoThe 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_version400NoThe 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_cursor400NoThe 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_line400NoThe line filter is not a valid phone number.Pass one of the numbers returned by GET /lines, in international format.
invalid_period400NoThe 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_request400NoThe 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_timezone400NoThe timezone is not a known IANA time zone.Use a name such as Europe/Rome, or omit it (default Europe/Rome).
not_reindexable400NoThis document cannot be re-indexed (it has no stored source).Delete it and add it again.
period_too_long400NoThe custom period is longer than 13 months.Split the range into shorter periods.
invalid_api_key401NoThe 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_available403NoThe 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_scope403NoThe 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_allowed403NoThe 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_suspended403NoThe 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_exhausted403NoThe 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_platform403NoThe endpoint was disabled by VoxAI staff (disabled_reason: platform), so it cannot be reactivated through the API.Contact support.
closure_not_found404NoThe agent has no closure with this id.Check the id with GET /agents/{agent_id}/closures.
not_found404NoThe 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_found404NoThe agent has no variable with this name.Check the name with GET /agents/{agent_id}/variables.
agent_configuration_unreadable409NoThe configuration of the agent cannot be read, so it cannot be changed safely.Contact support with the requestId.
agent_suspended409NoThe agent is suspended.Resume it with POST /agents/{agent_id}/resume, then retry.
already_exists409NoThe 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_call409Yes, same keyA 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_progress409YesAnother erasure request for the same number is running.Retry in a minute. If the other request completed, the data is already erased.
concurrent_modification409YesThe 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_content409NoA 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_unknown409NoA 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_state409NoThe 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_active409NoThe organization has no active plan (for example it expired).Renew the plan in the app.
name_conflict409NoA document with the same name already exists.Use another name, or delete the existing document first.
request_in_progress409Yes, same keyA 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_unavailable409NoThe 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_closures409NoThe agent already has the maximum number of upcoming closures (details.limit, 50).Delete a closure first.
too_many_variables409NoThe agent already has the maximum number of variables (details.limit, 30).Delete a variable first.
too_many_webhook_endpoints409NoThe organization reached the maximum number of webhook endpoints.Delete an endpoint before creating another.
variable_in_use409NoAn active campaign of the agent needs this variable.Pause or complete the campaigns in details.campaigns, then retry.
variable_not_static409NoThe 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_expired409NoThe 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_inactive409NoThe 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_large413NoThe 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_large422NoThis 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_reached422NoThe campaign would go over the maximum number of contacts (details.limit).Send fewer contacts, or create another campaign.
contact_origin_invalid422Nocontact_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_required422NoThe body has no contact_origin at all.Declare where the right to call comes from in contact_origin (see the field description).
destination_not_allowed422Noto 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_objected422NoThe 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_reused422NoThe 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_contacts422NoAt 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_url422NoThe 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_full422NoThe knowledge base of the organization has reached its storage limit.Delete documents you no longer need, then retry.
missing_variables422NoThe agent declares required variables that are not in variables.Send the variables listed in details.names (see GET /agents/{agent_id}/variables).
outside_calling_hours422YesNow 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_mismatch422Noconfirm_phone_number does not repeat phone_number exactly. Nothing was erased.Send the same number in both fields.
too_many_records422NoToo 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_type422NoOne 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_reached429YesThe 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_busy429YesAll 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_limited429YesToo 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)

CodeStatusRetryWhat it meansWhat to do
caller_erasure_incomplete500Yes, same keyThe 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_error500YesAn 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_unavailable502YesThe telephone network did not accept the call. Nothing was dialed.Retry after a few seconds with a NEW Idempotency-Key.
api_not_configured503NoThe API is not enabled on this service.Contact support.
knowledge_indexing_unavailable503YesIndexing 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_unavailable503YesA 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_error503YesThe 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_recorded503YesThe 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_configured503NoWebhooks are not enabled on this service.Contact support.