Errors
HTTP status is the truth. The body is a hint.
Shape
{
"error": {
"message": "Agent not found",
"status": 404,
"timestamp": "2026-09-11T10:00:00.000Z"
}
}message is meant for humans. Machine readable code sits inside error, on these responses:
error.code | Where |
|---|---|
RATE_LIMITED | 429 on any endpoint. |
schema_version_not_v3 | 400 on POST /v1/calls/schedule, when the worker's scheduled-calls job cannot be run. |
empty_process_steps | Same. |
pre_steps_unsupported | Same. |
branch_without_call | Same, and 422 on POST /v2/jobs/{id}/execute: a branch in a job that works through a contact list has no call step before it to decide on. |
stationed_job_has_no_contacts | 400 on POST /v2/jobs/{id}/contacts, POST /v2/jobs/{id}/execute, POST /v1/jobs/{id}/trigger and POST /v1/calls/schedule, when the job answers incoming calls or chats and so has no contact list. |
job_contact_required | 400 on POST /v2/jobs/{id}/execute without a jobContactId. |
job_has_no_steps | 422 on POST /v2/jobs/{id}/execute, when the job has no steps to run. |
No other response carries a code today, and the list of job refusals can grow. Branch on the HTTP status, not the body, and treat a code you do not recognise on that 400 as one more reason that job cannot run.
Some 404 and 500 responses carry "status": 400 in the body. Known, harmless, ignore the body field.
Statuses you will see
| Status | Meaning | Usually because |
|---|---|---|
| 400 | Bad request | Missing field, bad phone format, validation. Message tells you which. |
| 401 | No or bad key | Typo, expired, owner left the org. |
| 403 | Not allowed | Blocked phone number, job doesn't allow manual contacts, role too low. |
| 404 | Not yours or not there | Same response either way, on purpose. |
| 207 | Partial success | Batch endpoints. Read results[]. |
| 429 | Slow down | 1000 req/min per key. |
| 503 | Downstream is out | Chat worker unavailable. Retry with backoff. |
| 500 | Our bug, with one exception | Retry once, then tell us. The exception is POST /v1/calls/schedule, where a deleted job, or one left in a status that cannot be moved back to running, also answers 500 - that one is yours to fix. |
Validation messages
Zod backed endpoints (chat, knowledge, outbound calls, listings) return one 400 with every failing field joined:
{ "error": { "message": "Validation error: sources.0.title: title is required, sources.1.content: content too long (max 500KB)", "status": 400, "timestamp": "..." } }Older endpoints (agents, schedule, batch calls) check fields by hand and return the first problem only.
Malformed JSON
Depends on the endpoint. Some treat it as an empty body, one returns 500. Send valid JSON and Content-Type: application/json and this never comes up.