Error Codes

HTTP status codes, error response format, and handling guidance.

Error response format

All errors return a JSON body following the OpenAI error schema:

{
  "error": {
    "message": "Insufficient credit balance",
    "type": "insufficient_funds",
    "code": "balance_exceeded"
  }
}

Status codes

Status	Meaning	What to do
`400`	Bad request	Check your request body for malformed JSON or missing fields.
`401`	Unauthorized	Verify your API key is correct and starts with `tr-`.
`402`	Insufficient balance	Add credits or enable auto-recharge in your API Dashboard.
`404`	Model not found	Check the model ID against available models.
`429`	Rate limited	Wait for `Retry-After` seconds before retrying.
`500`	Internal server error	Retry after a brief delay. Contact support if persistent.
`502`	Provider error	Retry — the router will try an alternative provider if available.

Router-detected request problems

Some 400 responses are raised by the router before the request reaches a provider, because the request contradicts a published route contract. These carry a specific code and a message naming the fix.

Code	Cause
`unsupported_image_url`	A vision request used a remote `https://…` image URL on a provider that blocks them. Inline it as a base64 data URL instead — see Document OCR.
`unsupported_reasoning`	A `reasoning` or `reasoning_effort` field was sent to a route with no reasoning controls — see Reasoning controls.

502 is deliberately generic: an upstream failure the router cannot classify is reported as bad_gateway, so a provider's internal wording is never echoed back. When a 502 is not explained by the request, the provider's own message is in the router log.

Retry guidance

For exponential backoff, timeouts, and retry budgets, see Retries and transient errors.

If you want the router to try alternative routes inside one request, see Routing failover.

Models

Attestation