Errors | Tried Docs

Errors

The error body, every HTTP status code the API returns, and what causes each one.

Tried uses HTTP status codes to report the result of a request. Codes in the 2xx range mean success, 4xx means the request needs to change, and 5xx means something failed on the Tried side or at a vendor.

Error body#

Every error returns JSON with the status code repeated and a readable message:

{
  "status": 404,
  "message": "Not found"
}

Field	Type	Description
`status`	integer	The HTTP status code.
`message`	string	What went wrong. Validation errors name the field.
`error_code`	string	Only on some responses: `402` spend blocks (see 402) and `502` `provisioning_failed` from Provision phone number. A stable code you can branch on.

Match on status and error_code. Treat message as text for people: its wording can change.

Success codes#

Status	Used for
`200 OK`	Reads, updates and most actions. The body is the resource or result.
`201 Created`	Create endpoints, such as `POST /create-agent`, `POST /v2/create-phone-call` and `POST /create-knowledge-base`.
`202 Accepted`	Work that continues in the background, such as Create contact import job.
`204 No Content`	Deletes. The body is empty.

400 Bad Request#

The body failed validation, or a value is not allowed in the current state.

Validation errors list each failing field as path: issue, joined by ; . Nested fields use dots and array indexes:

{
  "status": 400,
  "message": "to_number: Required; retell_llm_dynamic_variables.name: Expected string, received number"
}

Other 400 messages you may see:

Message	Cause
`Invalid JSON body`	The body is not valid JSON.
`Invalid pagination_key`	The `pagination_key` on `POST /v3/list-calls` is not a call in this workspace.
`to_number <number> is not a valid E.164 number`	Phone numbers must be E.164, such as `+61291234567`.
`Call analysis can only be rerun on ended calls`	The call is still running.

Unknown fields in a request body are dropped, not rejected. Server-controlled fields such as IDs, versions and timestamps are never read from the body.

401 Unauthorized#

{ "status": 401, "message": "Missing or invalid API key / session" }

The Authorization header is missing, the key does not exist or was deleted, or a public key was used from an Origin it does not allow. See Authentication.

402 Payment Required#

The workspace cannot spend more right now. On call and chat creation routes, and on Conductor messages, the body includes error_code:

{
  "status": 402,
  "message": "Credit exhausted (balance $0.00). Add credits or turn on auto-recharge.",
  "error_code": "credit_exhausted"
}

`error_code`	Cause
`credit_exhausted`	The credit balance is zero or below.
`budget_reached`	The workspace's monthly budget is spent.
`invoice_overdue`	An invoice has been unpaid for 14 days or more. Pay it in Billing to resume calls.
`verification_needed`	The account needs verification before it can place outbound calls (`/v2/create-phone-call`, `/create-batch-call`).
`conductor_credits_exhausted`	Free Conductor credits for today are used and pay-as-you-go is off.
`conductor_limit_reached`	The Conductor monthly limit is reached.

The routes checked for spend are /v2/create-phone-call, /v3/create-web-call, /v2/register-phone-call, /register-phone-call, /create-batch-call, /create-chat, /create-chat-completion, /create-sms-chat and the hosted widget and share-link routes. Billing actions such as adding credits also return 402 (without error_code) when the payment fails.

403 Forbidden#

The key is valid but not allowed to do this.

Message	Cause
`This API key lacks the "<scope>" scope`	The key's scopes do not cover the route.
`This API key is not allowed from <ip>`	The key's IP allowlist.
`Requires role: admin`	A dashboard session without the needed role.
`The member role is read-only`	A dashboard session with the `member` role tried to write.
`Business verification (KYC) is <status>: it must be approved before you can <action>. Submit it with POST /kyc.`	The action needs approved business verification. See Submit KYC.
`A public key can only start web calls and chats`	A public key was used on another route.

404 Not Found#

The resource does not exist in this workspace, or the route does not exist.

{ "status": 404, "message": "Not found" }

{ "status": 404, "message": "Route GET /v2/get-agent/agent_123 not found" }

Resources in other workspaces also return 404, never 403, so IDs from another workspace cannot be probed. Some endpoints return a more specific message, such as API key not found or from_number +61291234567 is not a number in this workspace.

409 Conflict#

The request clashes with existing data.

Message	Cause
`Already exists`	A unique value (such as a name or number) is already taken.
`<phone_number> already exists`	The number is already in Tried.
`A contact with <phone_number> already exists`	Contacts are unique by phone number.
`<email> is already a member`	The user is already in the workspace.
`A request with idempotency_key <key> is still being processed`	A call with the same `idempotency_key` is being placed right now. Retry shortly to get the original call.

413 Payload Too Large#

Files are limited to 50 MB each on knowledge base uploads. JSON bodies are limited to 25 MB.

422 Unprocessable Entity#

The request was valid but a downstream step could not complete it, such as the number provider refusing a purchase or import, or SIP routing for register-phone-call not being configured. The message carries the provider's reason.

429 Too Many Requests#

A rate, concurrency or CPS limit was hit. See Rate limits for every limit and the headers to read.

{
  "status": 429,
  "message": "Rate limit exceeded for this API key: 600 requests per minute. Retry in 12s."
}

500 and 502#

500 Internal server error is an unexpected failure. In production the message is always Internal server error. 502 means a vendor (for example ElevenLabs) returned an error or could not be reached. Retry 5xx responses with backoff.