Error codes

Every error code, its HTTP status and fix.

Every response carries an x-request-id header (also visible in your Logs). Errors always use the error shape of the endpoint you called, with a stable machine-readable code.

Error shapes

OpenAI-compatible endpointsjson

{ "error": { "message": "Insufficient balance", "type": "insufficient_balance", "code": "insufficient_balance", "param": null } }

Anthropic-compatible endpointsjson

{ "type": "error", "error": { "type": "rate_limit_error", "message": "Too many concurrent requests" } }

Gemini-compatible endpointsjson

{ "error": { "code": 429, "message": "Too many concurrent requests", "status": "RESOURCE_EXHAUSTED" } }

Error codes

Code	HTTP	Meaning	How to fix
`invalid_api_key`	401	The API key is missing, malformed or does not exist.	Send your key as `Authorization: Bearer sk-pp-...` (or `x-api-key` / `x-goog-api-key`). Check for stray whitespace and that you copied the full key.
`key_disabled`	401	The key exists but was disabled or revoked.	Enable it on the API Keys page, or create a new key.
`key_expired`	401	The key passed its expiry date.	Create a new key (or clear the expiry on this one).
`ip_not_allowed`	403	The request came from an IP address that is not on the key's allowlist.	Add the IP/CIDR to the key's allowlist or remove the restriction.
`account_suspended`	403	Your account is suspended.	Contact support.
`email_not_verified`	403	Your email address has not been verified yet.	Open the verification link we emailed you (you can resend it from the login page).
`model_not_found`	404	No model with that name exists in the catalog.	Call `GET /v1/models` or see Models & Pricing for valid model ids.
`model_not_allowed`	403	The model exists but your key or pool is not allowed to use it.	Edit the key's allowed models, or switch the key to a pool that includes the model.
`unsupported_endpoint`	400	The model does not support this endpoint (for example chat on an embeddings model).	Use the right endpoint for the model's capabilities.
`insufficient_balance`	402	Your balance is too low to run this request.	Add funds on the Billing page; consider enabling auto-recharge.
`spend_limit_reached`	402	The key's spend limit or your monthly spend limit has been reached.	Raise the limit on the key or in your billing settings.
`rate_limited`	429	Too many requests per minute/tokens, or too many concurrent requests.	Back off and retry after the `retry-after` header; lower concurrency or raise the key limits.
`no_capacity`	429	All capacity was busy for longer than the queue timeout.	Retry after the `retry-after` header. Official SDKs do this automatically.
`no_available_provider`	503	No upstream is currently available for this model.	Retry shortly; check the Status page.
`upstream_timeout`	504	The upstream took too long to respond.	Retry; use streaming for long generations.
`upstream_error`	502	The upstream returned an error or was unreachable.	Retry with backoff. If it persists, share the request id with support.
`invalid_request`	400	The request body or parameters are invalid.	Check the error message for the offending field and compare with the provider API reference.
`internal_error`	500	Unexpected error on our side.	Retry; if it persists contact support with the request id.

Retry 429, 502, 503 and 504 with exponential backoff and honour retry-after. Do not retry 400, 401, 402, 403 or 404 without changing something first.