Skip to content
quebragalho/docs

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

StatuscodeWhat to do
400invalid_requestMalformed body. Check the JSON and the fields.
400max_tokens_exceeds_capLower max_tokens to your plan's cap.
400context_length_exceededThe conversation does not fit the model's context. Shorten or compact it.
400content_policy_violationThe provider refused the request's content.
401invalid_api_keyMissing, revoked or invalid API key. Create another one in the dashboard.
402insufficient_balanceYour available balance does not cover the hold. Top up.
402insufficient_paid_balanceThe model only accepts topped-up balance, and your topped-up balance does not cover it.
403model_not_allowedThe key has a model list that does not include this one.
404model_not_foundId outside the catalog. Query GET /v1/models.
429rate_limit_exceeded, concurrency_limit_exceededPer-minute or concurrent-request limit. Wait for Retry-After.
502 · 504upstream_error, timeoutProvider failure or slowness. They arrive as 503; try again shortly.
503wallet_unavailableA 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_tokens field of GET /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/usage and /v1/status.