ResoneraErrors & status codes
What each status means and how errors are shaped.
Errors return JSON with a readable error:
{ "error": "API key lacks required scope 'agents:write'", "status_code": 403, "timestamp": "2026-10-05 09:12:44" }A missing field or a field of the wrong type is caught before your request reaches us, and returns
422 in FastAPI's shape, which lists each problem with its location:
{ "detail": [ { "loc": ["body", "prompt"], "msg": "Field required", "type": "missing" } ] }Plan limits return 402 with an object in error that names the limit:
{
"error": { "error": "limit_exceeded", "limit": "agent_limit_exceeded", "message": "plan Starter allows 3 default agents" },
"status_code": 402
}Status codes
| Code | Meaning | What to do |
|---|---|---|
200, 201 | Success. | |
400 | The request can't be carried out, for example launching a campaign with no pending contacts. | Read error; don't retry unchanged. |
401 | Missing, malformed or revoked API key. | Check the X-API-Key header. |
402 | Out of balance, or a plan limit (agents, active agents, languages) is reached. | Top up or upgrade in the dashboard. |
403 | The key is valid but lacks the scope this endpoint needs. | Create a key with the scope. |
404 | Not found, or it belongs to another organization. | Check the id. |
422 | A field is missing or invalid. The message names it. | Fix the request. |
429 | This key's daily dispatch cap is reached. | Wait until 00:00 UTC, or raise the cap. |
500, 502, 503 | Something went wrong on our side, or with a telephony provider. | Retry with backoff. If a launch failed this way, check the campaign before retrying. |
Retrying safely
Reads (GET) are always safe to retry. Before retrying a POST that timed out, check whether it
took effect. For example, list your campaigns before creating the same batch again, and check
contacts_by_status before launching again.