Errors & Troubleshooting
Understand validation failures, activation conflicts, and failed conversations.
Check the HTTP status and response body before using a result. Public API failures normally include an error string, with optional code, details, or validation issues. Do not assume every error has a machine-readable code.
{
"error": "Agent update conflict",
"details": "Agent changed since expectedUpdatedAt; refetch and retry."
}
Resolve API failures
| Status | Likely cause | What to do |
|---|---|---|
400 | Invalid UUID, missing field, invalid enum, or unsupported configuration | Read issues[].path and issues[].message when provided. Required nullable fields still need null in full create requests. |
401 | Missing, invalid, or revoked API key | Send the full key in Authorization: Bearer …; verify the key belongs to the intended organization. |
403 with FEATURE_NOT_AVAILABLE | Requested feature is unavailable on the account plan | Remove the unavailable setting or change the plan. For example, leave ambient sound as none. |
404 | Resource absent or outside the key's organization | List resources using the same key and use the returned UUID. SIP also returns 404 when disabled. |
409 with AGENT_LIMIT_EXCEEDED | Activation exceeds the active-agent allowance | Check maxAgents, deactivate an unused agent, or change the plan. Drafts do not consume active-agent slots. |
409 with Agent update conflict | PATCH revision is stale | GET the agent, review concurrent changes, and PATCH using its new agent.updatedAt. |
409 for a realtime session | Agent is not active | Activate it before requesting a public realtime session. |
500 for a realtime session | Server-side session configuration failed | Retry later; if persistent, report the endpoint, time, status, and sanitized error. |
502 for knowledge upload | Knowledge ingestion failed | Retry later after checking document format and text content. |
Endpoint-specific errors are listed with agents, phone numbers, MCP integrations, and SIP.
An agent exists but cannot take calls
Check its status with GET /public/v1/agents/{agent_id}. Creation always produces a draft. For phone calls, also check that the number is claimed, its carrier setup is complete, and it is assigned to this agent. For browser calls, request a fresh session and connect before expiresAt; do not reuse a cached URL.
A tool is missing or fails
- Static agents do not accept custom HTTP/webhook tools. The agent type cannot be changed after creation.
- HTTP tools require
toolUrl. Verify HTTPS, endpoint credentials, method, parameters, and timeout. Private-network destinations are blocked by the runtime. - Webhook tools require a saved agent
serverUrl. Dispatchmessage.toolCall.nameand verify signatures against the raw request body. - Confirm the tool is enabled and its description tells the model when to invoke it. Registration does not guarantee every conversation will call it.
- Review call detail and agent logs. Logs expose a rolling 24-hour window.
Retry without duplicating work
After a network timeout on a create or other write, first check whether it succeeded. Blind retries can create duplicate agents, tools, or external actions. For reads and transient service failures, retry with a bounded delay. For validation and authentication failures, correct the request first. For revision conflicts, refetch and reconcile rather than repeating the stale PATCH.
When sharing diagnostics, include the method, path, time, status, resource ID, and sanitized response. Remove API keys, webhook secrets, authentication headers, and caller data.