Skip to main content

​
Error format

All errors return a JSON body with a detail field: 
{
  "detail": "Human-readable error message"
}
For request validation failures (status 422), detail is an array of field-level errors: 
{
  "detail": [
    {
      "loc": ["body", "phone_number"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

​
HTTP status codes

StatusMeaningCommon causes
400Bad RequestMissing required fields, invalid parameter values, unsupported operation
401UnauthorizedMissing auth header, invalid or expired API key or JWT token
403ForbiddenValid credentials but the resource belongs to a different organization
404Not FoundResource ID does not exist or is not accessible to your organization
409ConflictDuplicate resource (e.g., email already registered)
422Unprocessable EntityRequest body or query parameter failed schema validation
500Internal Server ErrorUnexpected server-side failure
501Not ImplementedFeature not supported in the current deployment

​
Workflow validation errors

When validating a workflow (or creating one with invalid nodes), the API returns structured errors that reference specific nodes, edges, or fields: 
{
  "errors": [
    {
      "kind": "node",
      "id": "agent-1",
      "field": "data.prompt",
      "message": "Prompt cannot be empty"
    },
    {
      "kind": "edge",
      "id": "edge-3",
      "field": null,
      "message": "Edge target node does not exist"
    },
    {
      "kind": "workflow",
      "id": null,
      "field": null,
      "message": "Workflow must have exactly one Start Call node"
    }
  ]
}
FieldTypeDescription
kind"node" | "edge" | "workflow"What the error applies to
idstring or nullNode or edge ID from the workflow definition
fieldstring or nullDot-notation path to the specific field (e.g. data.prompt)
messagestringHuman-readable description of the problem

​
Telephony errors

Telephony operations may fail with one of these named error types returned in the detail field:
ErrorDescription
PROVIDER_MISMATCHThe request was routed to the wrong telephony provider
WORKFLOW_NOT_FOUNDThe workflow ID in the inbound URL does not exist
ACCOUNT_VALIDATION_FAILEDYour telephony provider credentials are invalid
PHONE_NUMBER_NOT_CONFIGUREDThe phone number is not set up in your telephony account
SIGNATURE_VALIDATION_FAILEDWebhook signature verification failed (possible spoofed request)
QUOTA_EXCEEDEDYour organization has exceeded its usage quota
GENERAL_AUTH_FAILEDGeneric authentication failure with the telephony provider

​
Tips for handling errors

  • Retry on 500 with exponential backoff — transient server errors can resolve on retry.
  • Do not retry 4xx — these indicate problems with your request that will not self-resolve.
  • Check detail carefully on 422 — the loc array pinpoints exactly which field failed validation.
  • Store API keys securely — a 401 on a previously working key likely means the key was archived.