API reference
Errors and limits
The error format, what each code means and the API limits: balance hold, output cap, requests per minute and concurrency.
An error object with a code
Each route answers in the error format of the API it mirrors. On /v1/chat/completions it is OpenAI's: an error object with message, type and code. Read the code, not just the status.
Response · 400
{ "error": { "message": "max_tokens exceeds plan limit", "type": "invalid_request_error", "code": "max_tokens_exceeds_cap" }}The Anthropic format (/v1/messages) and the Responses format have their own tables: see Messages and Responses.
The most common codes
| Status | code | What to do |
|---|---|---|
| 400 | invalid_request | Malformed body. Check the JSON and the fields. |
| 400 | max_tokens_exceeds_cap | Lower max_tokens to your plan's cap. |
| 400 | context_length_exceeded | The conversation does not fit the model's context. Shorten or compact it. |
| 400 | content_policy_violation | The provider refused the request's content. |
| 401 | invalid_api_key | Missing, revoked or invalid API key. Create another one in the dashboard. |
| 402 | insufficient_balance | Your available balance does not cover the hold. Top up. |
| 402 | insufficient_paid_balance | The model only accepts topped-up balance, and your topped-up balance does not cover it. |
| 403 | model_not_allowed | The key has a model list that does not include this one. |
| 404 | model_not_found | Id outside the catalog. Query GET /v1/models. |
| 429 | rate_limit_exceeded, concurrency_limit_exceeded | Per-minute or concurrent-request limit. Wait for Retry-After. |
| 502 · 504 | upstream_error, timeout | Provider failure or slowness. They arrive as 503; try again shortly. |
| 503 | wallet_unavailable | A brief hiccup on our side. Wait for Retry-After. |
502 and 504 responses arrive as 503: Cloudflare, in front of the API, swaps those statuses. Read the type and the code in the body, not just the status.
Hold, cap and pace
Hold- Before each response, your balance sets aside a hold based on the request size and the output cap. At the end, it charges only what was generated and returns the rest.
Output cap- Each plan has an output cap per model. The one that applies to your key is in the
max_output_tokensfield ofGET /v1/models. Per minute and concurrent- The requests-per-minute and concurrent-request limits come from your plan. Above them, 429 with
Retry-After. Account API- Up to 60 reads per minute per key on
/v1/balance,/v1/key,/v1/usageand/v1/status.