Errors

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", "to_number"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

HTTP status codes

Status	Meaning	Common causes
`400`	Bad Request	Missing required fields, invalid parameter values, unsupported operation
`401`	Unauthorized	Missing auth header, invalid or expired API key or session token, or an `X-API-Key` sent to a session-only route
`402`	Payment Required	Your organization is out of credits, or has reached its daily spend cap
`403`	Forbidden	Valid credentials but the resource belongs to a different organization, or the caller’s role is too low
`404`	Not Found	Resource ID does not exist or is not accessible to your organization
`409`	Conflict	Duplicate resource (e.g., email already registered)
`422`	Unprocessable Entity	Request body or query parameter failed schema validation
`429`	Too Many Requests	A per-organization rate limit or per-key concurrency limit was exceeded
`500`	Internal Server Error	Unexpected server-side failure
`501`	Not Implemented	Feature not supported in the current deployment
`503`	Service Unavailable	A required upstream (model plane, telephony provider, engine) is not configured or not reachable

Authentication errors

401 covers three distinct situations. The detail field tells them apart:

`detail`	Meaning
`Invalid or expired API key`	The `bibha_…` key was archived, revoked, or never existed
`User session required`	An `X-API-Key` was sent to `/admin/`, `/sa/` or `/superuser/*`. These routes take an interactive session only — see Authentication
`Authorization header required`	No credential was sent at all

MPS service-key routes (/api/v1/mps/*) return their own 401 messages and use a different credential entirely — see MPS service keys.

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"
    }
  ]
}

Field	Type	Description
`kind`	`"node" \| "edge" \| "workflow"`	What the error applies to
`id`	string or null	Node or edge ID from the workflow definition
`field`	string or null	Dot-notation path to the specific field (e.g. `data.prompt`)
`message`	string	Human-readable description of the problem

Telephony errors

Telephony operations may fail with one of these named error types returned in the detail field:

Error	Description
`PROVIDER_MISMATCH`	The request was routed to the wrong telephony provider
`WORKFLOW_NOT_FOUND`	The workflow ID in the inbound URL does not exist
`ACCOUNT_VALIDATION_FAILED`	Your telephony provider credentials are invalid
`PHONE_NUMBER_NOT_CONFIGURED`	The phone number is not set up in your telephony account
`SIGNATURE_VALIDATION_FAILED`	Webhook signature verification failed (possible spoofed request)
`QUOTA_EXCEEDED`	Your organization has exceeded its usage quota
`GENERAL_AUTH_FAILED`	Generic 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.
Read the 401 detail before rotating — User session required is not a bad key; it means the route does not accept API keys at all.
Back off on 429 — honour any Retry-After header and reduce concurrency rather than retrying immediately.
Treat 402 as “top up”, not “retry” — model requests (BRAHMA, VAANI, LIPI, embeddings, moderation, deep research, transcription and the Voice Engine) draw on your organization’s credit balance. A 402 means the balance is exhausted or the daily spend cap is reached; the detail field says which. Retrying will not help until credits are added, the cap is raised, or you supply your own provider keys.

Resources

Authentication & Errors

Voice Engine API

Bibha BRAHMA LLM

Bibha VAANI TTS

Bibha LIPI STT

Error format

HTTP status codes

Authentication errors

Workflow validation errors

Telephony errors

Tips for handling errors

​Error format

​HTTP status codes

​Authentication errors

​Workflow validation errors

​Telephony errors

​Tips for handling errors

Error format

HTTP status codes

Authentication errors

Workflow validation errors

Telephony errors

Tips for handling errors