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.
| Field | Holds |
|---|---|
type | A link to the code below |
title | The HTTP status in words, or Confirmation required on confirmation_required |
status | The HTTP status |
detail | What went wrong and what to change; it may be reworded |
code | The stable code: branch on this |
errors | On invalid_input, one { path, message } per field |
estimate | On confirmation_required for an operation that spends credit |
retryAfterSeconds | On 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.