Get started
Errors
The one error shape, the status codes in use, and how to report a failure.
Shape
Every 4xx and 5xx response has the same JSON body. error repeats the HTTP status; message is written for a person.
{"error": 404, "message": "Agent not found"}A 500 also carries the id of the request, which is the thing to send to support:
{"error": 500, "message": "Internal server error", "request_id": "a3c1f0d2b7e94c55"}Request ids
Every response has an X-Request-Id header. If you send your own X-Request-Id, the platform uses it (when it is a sane token) and writes it on every log line of that request. Log it on your side for anything you may need to trace.
Status codes
| Status | When |
|---|---|
| 400 | The request is invalid: a missing field, a bad format, a failed validation, or a call refused by a compliance rule. The message names the field or the rule. |
| 401 | No valid token. See Authentication. |
| 403 | The role may not do this, or the email address is not verified yet. |
| 404 | Not found, or owned by a different workspace. The answer is the same in both cases. |
| 409 | A conflict: an Idempotency-Key reused with a different request, or an action that the object's state does not allow. |
| 413 | The body is too large (2 MB by default outside the upload routes). |
| 429 | A rate limit, a throttle, or a per-number call cap. See Rate limits. |
| 500 | A fault on our side. Safe to retry with the same Idempotency-Key. |
| 503 | A dependency is unavailable, for example the setup assistant with no AI backend configured. |
Validation messages
Field errors are reported one at a time, as <field path>: <problem>:
{"error": 400, "message": "recipient_phone_number must be in E.164 format, e.g. +919876543210"}Fix the field and send again; the next problem, if any, is reported then.
Call failures are not HTTP errors
POST /call returns 200 the moment it accepts the call. What happens to it afterwards (no answer, busy, a failure at the provider, no balance) is reported on the execution: its status and, for failures, its error_message. Read the execution or use a webhook; do not infer the outcome from the response to POST /call.
Retrying
- Retry 429 and 5xx with exponential backoff.
- Send an
Idempotency-Keyon requests that create or spend, so a retry cannot repeat the action. - Do not retry 400, 401, 403 or 404 without changing the request.