Docs

Errors

The error envelope and what every code we emit actually means.

The error envelope

The same shape OpenAI returns, so your existing error handling works. The code field is the precise one — branch on it, never on the message text.

json

{
  "error": {
    "message": "insufficient balance",
    "type": "insufficient_quota",
    "code": "insufficient_balance"
  }
}

code	Meaning and what to do
`invalid_request`	The body is malformed — the message names the field.
`request_exceeds_token_limit`	prompt + max_tokens exceeds your whole tokens-per-minute allowance. Retrying never fixes this: shorten the prompt or lower max_tokens.
`streaming_disabled`	Streaming is temporarily off. Re-send with stream=false.

code	Meaning
`invalid_api_key`	Wrong, revoked or expired key. The most common real cause is a stray space or newline from copying.

code	Meaning and what to do
`insufficient_balance`	Not enough balance to cover this request's hold. Top up — or lower max_tokens so the hold shrinks.
`monthly_cap_reached`	This key's monthly spend cap is exhausted.
`plan_quota_reached`	The plan's token allowance is spent and the plan allows no overage.
`overage_disabled`	Allowance spent and overage is not enabled for this account. Enable it, or switch the key to credit.
`overage_limit_reached`	The overage ceiling is exhausted.

code	Meaning and what to do
`model_not_allowed`	This key is deliberately restricted to a specific model list.
`model_not_in_plan`	The model is outside your plan. Switch the key to credit to reach every model from your wallet — details.
`byok_disabled`	Bring-your-own-key is switched off platform-wide.

code	HTTP	Meaning
`model_not_found`	404	Unknown model ID — either it does not exist or it is unpublished.
`rate_limit_rpm / rph / rpd / tpm`	429	That window's rate limit is full. Honour retry-after.
`key_daily_token_budget_reached`	429	The key's daily token budget. Resets at Tehran midnight.
`key_daily_budget_reached`	429	The key's daily Rial budget.
`free_daily_limit`	429	The free plan's daily ceiling.
`global_throttle`	429	A temporary platform-wide throttle during a spike.
`no_capacity`	503	No healthy route for this model right now. Retry shortly.
`gateway_paused`	503	The service is in maintenance mode.
`pricing_unavailable`	503	No active rate to price with; we would rather not charge blind.

Which are worth retrying and which are not:

Retryable: 429 (after retry-after), 503 no_capacity, 5xx upstream — with exponential backoff.
Pointless: 400, 401, 403, 404 — the answer will not change until the request does.
Needs a human: 402 — a top-up or a settings change is required.

Send the x-request-id header value. With it we find the exact request — without it we are guessing.