Gateway errors and status codes

Shape

On /v1/chat/completions, /v1/models and /v1/key, errors use OpenAI's shape:

{
  "error": {
    "message": "This API key's budget is used up.",
    "type": "budget_exceeded",
    "code": "budget_exceeded"
  }
}

On /v1/messages, they use Anthropic's shape, without code:

{
  "type": "error",
  "error": {
    "type": "budget_exceeded",
    "message": "This API key's budget is used up."
  }
}

message is written for people and may change; match on type and code in code.

Every error

Status	`type`	`code`	When	What to do
401	`authentication_error`	none	The key is missing, wrong, disabled, deleted or expired, or is a master key.	Send a live API key as `Authorization: Bearer <key>` or `x-api-key`.
403	`permission_error`	none	The key's project or organisation isn't active, or the caller's IP isn't on the key's allow list.	Check the project in the dashboard, or the key's IP rules.
413	`invalid_request_error`	none	The body is over the size limit (20 MB).	Send smaller images or files, or fewer of them.
400	`invalid_request_error`	none	The body isn't JSON, `model` or `messages` is missing, or `max_tokens` is missing on /v1/messages.	Fix the request body; the message names the field.
400	`invalid_request_error`	`content_blocked`	A guardrail blocked the request.	Change the content, or the guardrail rule in the dashboard.
404	`not_found_error`	`model_not_found`	No model has that ID or alias.	List models with `GET /v1/models`.
400	`invalid_request_error`	`capability_mismatch`	No provider of the model can do what the request needs (tools, images, JSON schema, reasoning, streaming or context size).	Choose another model, or `auto`.
403	`permission_error`	`model_not_allowed`	The key's or organisation's rules don't allow the model or provider.	Use an allowed model, or change the rules.
403	`permission_error`	`devpass_provider_pinned`	A DevPass key asked for `provider/model`.	Send the model ID alone; DevPass chooses the provider.
402	`insufficient_quota`	`devpass_inactive`	The DevPass key's organisation has no active pass.	Start or renew the pass.
402	`insufficient_quota`	`devpass_paused`	The pass is paused.	Contact support.
402	`insufficient_quota`	`devpass_monthly_limit`	The pass's monthly allowance is used up.	Wait for the time in `Retry-After`, or upgrade.
402	`insufficient_quota`	`devpass_daily_limit`	Today's share of the allowance is used up.	Wait for the time in `Retry-After`.
402	`insufficient_quota`	`devpass_premium_limit`	This week's premium-model share is used up.	Use a non-premium model or `auto`, or wait for `Retry-After`.
429	`rate_limit_error`	`devpass_concurrency`	The DevPass key already has its maximum requests in flight.	Wait for a request to finish.
429	`rate_limit_error`	`rate_limited`	Your organisation passed its requests per minute, or a per-minute or per-day rule on a model or provider.	Slow down and retry after a short wait.
429	`spend_cap_reached`	`daily_cap`	Your organisation reached its daily spend cap for its tier.	Wait until tomorrow (UTC), or ask support to raise it.
429	`spend_cap_reached`	`monthly_cap`	Your organisation reached its monthly spend cap for its tier.	Wait for next month, or ask support to raise it.
429	`budget_exceeded`	`budget_exceeded`	A budget on the key, member or team is used up.	Raise the budget in the dashboard, or wait for it to reset.
402	`insufficient_credits`	`insufficient_credits`	The request runs on credits and the balance is too low.	Top up, or add your own provider key.
503	`api_error`	`no_provider_available`	The model exists but no provider can take the request right now.	Retry shortly, or choose another model.
502	`api_error`	`provider_failed`	Every provider tried for the request failed.	Retry shortly.
500	`api_error`	none	Something failed inside the gateway.	Retry; if it continues, contact support with the `x-request-id`.

Errors from providers

When a provider turns a request down with a 4xx other than 429, the gateway returns the provider's status with type invalid_request_error and the message "The provider rejected the request: …", followed by the provider's own explanation. It doesn't try another provider, because the request itself is the problem. Fix the request, or try another model.

What to retry

Status	Retry?
`429 rate_limit_error`	Yes, after a short wait that grows with each attempt (for example 1, 2, then 4 seconds).
`402` DevPass limits	After the `Retry-After` header's seconds.
`502`, `503`, `500`	Yes, a few times with growing waits. The gateway has already tried other providers.
`429 budget_exceeded`, `429 spend_cap_reached`, `402 insufficient_credits`	Not until the budget, cap or balance changes.
`400`, `401`, `403`, `404`, `413`	No. Fix the request, key or rules first.

Only DevPass limit errors carry Retry-After. Other 429s don't, so choose your own wait.