Errors

Every error response has this shape:

{
  "error": "stable_code",
  "message": "Short human-readable description.",
  "request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b"
}

error: the stable code. Program against this field, not against message or the HTTP status (we sometimes share a status across different causes).
message: short text to show a human or to log.
request_id: UUID of the request. If you report a problem, send us this value: with it we can pinpoint what happened in seconds.

Some responses (a failed gate) include extra fields:

{
  "error": "payment_required",
  "message": "Account is not in good standing.",
  "primary_reason": "wallet",
  "reasons": ["wallet"],
  "request_id": "..."
}

Catalog

HTTP	`error`	Typical cause	What to do
400	`invalid_json`	The body is not valid JSON.	Check the `Content-Type` and the body.
400	`invalid_body`	Missing fields or fields with the wrong type.	The `message` tells you which field. Fix it and send it again.
400	`invalid_idempotency_key`	`Idempotency-Key` with forbidden characters or over 255 chars.	Use printable ASCII only. UUID v4 is the safest option.
400	`invalid_confirmation`	MCP only: the `confirmation_token` expired, was already used, belongs to another key or tool, or the arguments changed.	Call the tool again without the token to get a new one.
401	`unauthorized`	Missing, malformed, invalid or revoked API key.	Check the `Authorization` header. If the key was revoked, create a new one.
402	`payment_required`	Empty wallet or inactive subscription.	Top up the wallet or bring the subscription current. Check the `primary_reason` field.
402	`key_budget_exhausted`	This API key’s credit budget for the month does not cover the call or batch. Calls in progress hold part of it until they are billed.	Wait for calls in progress to finish, raise the limit in Settings > API keys, or wait for next month.
403	`agent_not_found`	The `agent_id` does not exist, or it exists but does not belong to your account.	Check that the ID is right and that the key belongs to the same customer as the agent.
409	`idempotency_conflict`	`Idempotency-Key` reused with a different body.	Generate a new key or reuse exactly the same body as the first request.
409	`idempotency_in_progress`	A request with the same `Idempotency-Key` is still running.	Retry in a few seconds with the same key: you will get the original response.
422	`agent_disabled`	The agent is paused (manually or by the system).	Reactivate the agent from the portal.
429	`rate_limit_exceeded`	Too many requests per minute, from your IP or from your account (by plan).	Wait the seconds in `Retry-After` and use exponential backoff. Read Rate limits.
500	`internal_error`	Unexpected error on our side.	Retry after a few seconds. If it persists, contact us with the `request_id`.
502	`upstream_unreachable`	We could not reach the telephony provider.	Retry with backoff. If it persists, write to us.
502	`upstream_error`	The provider rejected the call (for example, a number that account cannot use).	Check the number and the agent’s permissions. The `message` may give more context.
503	`rate_limit_unavailable`	We could not check your rate limit right now. It is not your quota running out.	Retry after the seconds in `Retry-After` (5). Read Rate limits.
503	`service_unavailable`	Missing configuration or temporary degradation.	Retry. If it persists, contact us.
503	`confirmation_unavailable`	MCP only: we could not check that a `confirmation_token` is used once, so nothing ran.	Retry shortly: call the tool again without the token to get a new one.

Denial reasons (`primary_reason`)

When the HTTP status is 402 or 422, the primary_reason field tells you why:

Value	What it means
`wallet`	Not enough balance. Top up from the portal.
`sub:canceled`	Subscription canceled.
`sub:past_due`	Payment past due.
`sub:unpaid`	Payment not processed.
`agent:pausado`	Agent paused manually.
`agent:sin_configurar`	Agent has not finished setup.
`denied`	Another reason (check `reasons`).

Best practices for handling errors

Program against error, not against message

The message field may get rewritten for clarity. The error is the contract: it does not change.

Always log the request_id

It is what we ask for when you report a bug. Without that ID, finding the request takes us minutes to hours.

Retry only 5xx and 429

4xx errors (except 429) are on the client side, so retrying will not fix them.

Exponential backoff with jitter

For 429 and 5xx, wait 1s, 2s, 4s, 8s with a bit of randomness so retries do not sync up.

Get started

Concepts

Webhooks

MCP server

Command line

Catalog

Denial reasons (`primary_reason`)

Best practices for handling errors

​Catalog

​Denial reasons (primary_reason)

​Best practices for handling errors

Catalog

Denial reasons (`primary_reason`)

Best practices for handling errors