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