Errors

Every REST error is a JSON body with a single error string (some responses add a hint):

{ "error": "Agent not found" }

Status conventions

Status	Meaning	Typical causes
400	Invalid request	Missing/malformed fields, bad JSON, invalid E.164
401	Unauthorized	Missing/invalid Bearer token or API key
403	Forbidden	Signature verification failed, out-of-scope key
404	Not found	Wrong id, or the resource belongs to another account
409	Conflict	Number already assigned to another agent
429	Rate limited	Includes a Retry-After header (seconds)
502	Upstream failure	Telephony or TTS provider error — safe to retry
503	Not configured	A capability's provider isn't set up on this deployment

Retry guidance

• 429 — wait Retry-After seconds, then retry.
• 502 — retry with backoff; use Idempotency-Key on calls and idempotency_key on messages so retries never double-dial or double-text.
• 409 on numbers — release the number from its current agent first.

MCP errors

The MCP endpoint returns JSON-RPC 2.0 error objects ({"jsonrpc", "id", "error": {"code", "message"}}) with HTTP 200, per protocol convention. Auth failures surface as JSON-RPC errors, not HTTP 401s.