Connect

API errors

Every error code the REST API returns, its HTTP status, and what to do about it.

Every error from the REST API is an RFC 9457 problem details object, sent as application/problem+json. Its type links to the code on this page.

FieldHolds
typeA link to the code below
titleThe HTTP status in words, or Confirmation required on confirmation_required
statusThe HTTP status
detailWhat went wrong and what to change; it may be reworded
codeThe stable code: branch on this
errorsOn invalid_input, one { path, message } per field
estimateOn confirmation_required for an operation that spends credit
retryAfterSecondsOn rate_limited

An operation can add its own fields, such as required (the missing scope) on insufficient_scope.

Authentication

unauthorized

401. The request carried no access token. Send one as Authorization: Bearer vai_pat_…; create it in Settings > API tokens.

invalid_token

401. The token is unknown, revoked or expired, it is pinned to a workspace its holder has left, or its holder no longer meets the workspace's two-factor rule. Create a new token.

untrusted_caller

401. The bearer token is a signed identity token (a JWT) from an identity provider that trusted callers use, and no workspace trusts its caller, or it failed verification: its signature, issuer, subject, audience, expiry or required claims did not match. A workspace admin adds a trusted caller with the add_trusted_caller operation.

staff_token_not_accepted

403. A staff token cannot use the API. Use a personal access token.

session_unavailable

503. The API could not start a session for the token. Nothing changed; try again.

Access

insufficient_scope

403. The token's access does not cover this operation. required names what it needs: agent:write for a change (a token with Edit access), agent:delete for a deletion (Edit with Delete allowed), or workspace:admin for members, phone numbers, webhooks and connected apps (Edit with Manage the workspace allowed). Make a token with that access under Settings > API tokens.

insufficient_role

403. Your role in the workspace cannot do this, for example a member managing webhooks, which needs an owner or admin.

workspace_out_of_scope

403. The token is pinned to another workspace.

workspace_scope_required

403. Your access in the workspace is limited to some agents, and this belongs to the whole workspace, such as its contacts or its member list.

signed_in_session_required

403. The operation works only for someone signed in to the app, such as listing your access tokens. An access token cannot run it.

operation_not_allowed

403. A trusted caller asked for an operation its workspace did not allow it.

not_available

403. The feature is not switched on for this workspace.

Not found

route_not_found

404. No route matches the path. Check it against the API reference.

method_not_allowed

405. The path exists but not with this method. The Allow header lists the methods it takes.

operation_not_found

404. No operation by that name at /operations/{name}.

agent_not_found

404. No agent with that slug in that workspace that you can reach. GET /workspaces/{workspace}/agents lists them.

workspace_not_found

404. No workspace with that slug that you can reach. GET /me lists yours.

Other not-found codes

404. A code ending in _not_found, such as webhook_not_found, campaign_not_found or delivery_not_found, names the record that is missing.

Input

invalid_input

400. An input failed validation, was not one the operation takes, contradicts the path, or was a value the operation refused; detail names it. An id in the path that is not one, such as a malformed webhook id, is refused here too. errors lists each field. Nothing changed.

invalid_json

400. The body is not a JSON object.

bad_agent

400. The agent is not a workspace-slug/agent-slug handle.

bad_cursor

400. The cursor is not one this list returned. Start again without it.

Confirmation and limits

confirmation_required

409. The operation deletes something, publishes, changes what live callers get straight away, or spends credit, and the request did not confirm it. Nothing changed. Repeat it with "confirm": true in the body, or ?confirm=true on a DELETE, once the person responsible has agreed. An operation that spends credit includes its estimate.

idempotency_key_in_use

409. A request with this Idempotency-Key is still running. Nothing else ran. Send it again once it finishes to get its answer.

idempotency_key_reused

422. This Idempotency-Key was sent in the last 24 hours with a different request. Nothing ran. Use a new key for a new request. See Retry safely.

rate_limited

429. The token made more than 600 requests in a minute. Nothing changed. Wait Retry-After seconds, then send it again.

plan_required

402. The workspace has no plan yet, or this needs a paid plan, such as starting from a template. Nothing ran. The workspace owner chooses a plan under Plan and usage.

plan_feature_locked

402. The workspace's plan does not include the feature this turns on or creates, so nothing changed. detail names the plans that include it. Change plan, then send the same request again.

trial_used

402. The workspace is on its trial and has used the trial's allowance for this, such as its voice test calls. Nothing ran. Choose a plan to carry on.

card_required

402. The workspace has no card for something that costs money, such as a test run. Nothing ran. Add a card under Plan and usage, then send the same request again.

account_past_due

402. The workspace's last payment did not go through. Nothing ran. Update the card under Plan and usage, then send the same request again.

spend_cap_reached

402. The workspace has spent its limit for this billing period. Nothing ran. Change the limit under Plan and usage.

subscription_canceled

402. The workspace's subscription is cancelled. Nothing ran. Manage it under Plan and usage.

plan_agent_limit

409. The workspace already has as many agents as its plan includes, so creating or duplicating one was refused and nothing changed. Archive an agent or change plan, then send the same request again.

Refusals

not_draft

409. The change is to a version, and the agent's latest version is published, so there is no draft to change. Nothing changed. Open a draft with POST /workspaces/{workspace}/agents/{agent}/versions (the create_draft operation), then send it again. PATCH on an agent opens one itself.

operation_failed

422. The operation refused the request for a reason in detail, such as a value that is not allowed. Change what it names and try again.

payload_expired

422. A webhook event's body is no longer kept, so it cannot be redelivered. See Redeliver an event.

Other codes

422, unless listed on this page. An operation can refuse with its own code, such as phone_number_taken (409) or webhook_inactive. detail says what to do. A code that names a conflict with the record's state, such as owner_change_refused, model_in_use or reserved_number, answers 409; a workspace that is read only answers 403 workspace_read_only. Some operations set the status themselves, such as 400 no_scenarios when a test run has no tests to run.

Server errors

tool_threw

500. The operation failed unexpectedly. Check whether the change happened before you try again.

Other server codes

500. read_failed, query_failed, write_failed, create_failed, restore_failed, sync_failed and audit_failed mean the operation could not finish reading or saving. Check whether the change happened before you try again.

idempotency_unavailable

503. The API could not record the Idempotency-Key, so the request did not run. Send it again.

On this page