Errors

Error response formats, what common HTTP status codes mean and how to handle them.

Error format

Error messages are always in English and end with a request id. Include this ID when you contact support — it lets us locate the problem quickly.

OpenAI-compatible endpoints and gateway-level errors (authentication, balance, parameters, etc.):

{
  "error": {
    "message": "invalid API key (request id: req-01e560f92fb2476ebd41a28f02d9d568)",
    "type": "...",
    "code": "..."
  }
}

Errors returned by the model on the Claude Messages endpoint keep Anthropic's official format:

{ "type": "error", "error": { "type": "invalid_request_error", "message": "..." } }

Volcengine Ark-compatible endpoints:

{ "error": { "code": "authentication_error", "message": "...", "type": "invalid_request_error" } }

If a streaming request fails after output has started, the error is sent as the last event (data: {"error": {...}} in OpenAI format, event: error in Claude format). Handle it in your client.

Original errors from model providers

Errors decided by the model provider, such as parameter validation and content safety checks, are passed on with the provider's original English message whenever possible (for example DeepSeek's thinking mode requiring reasoning_content to be sent back, video input moderation, or image content safety refusals), so you can fix the request directly. These errors are about the request itself; retrying on another route will not help, so the gateway does not retry them on other routes for you.

Problems unrelated to your request that come from the route itself are rewritten into a neutral English message, with one of these code values:

`code`	Meaning	What to do
`upstream_rejected`	The upstream rejected the request (4xx)	Check the request parameters against `message`
`upstream_rate_limited`	The upstream is rate limiting	Retry later
`upstream_unavailable`	The upstream is temporarily unavailable	Retry later, or switch to another group / model

Status codes at a glance

Status	Meaning	Common causes	What to do
`400`	Invalid request	Malformed JSON, missing required parameter, parameter value not supported by the model	Fix the request according to `message`; don't retry
`401`	Authentication failed	Key missing, wrong, deleted, expired or out of quota	Check the key; if out of quota, adjust it in the console
`403`	Forbidden	Insufficient balance; the key doesn't allow this model / group / IP	Top up or change the key settings
`404`	Not found	Typo in the URL; `/v1` added or missing	Check the base URL; see Overview
`429`	Rate limited	Too many requests, or the upstream is temporarily rate limiting	Retry with exponential backoff
`500`	Internal error	Occasional failure	Retry later; contact support if it persists
`502` / `503` / `504`	Upstream unavailable	Routes busy, or no route currently available for the model	Retry later, or switch to another group / model

Common error messages

Message	Status	Meaning
`no API key provided`	401	The request has no key; check how you set the header (see Authentication)
`invalid API key`	401	The key doesn't exist or was deleted
`this API key has run out of quota`	401	The key's quota is used up; raise it or set it to unlimited in the console
`this API key has expired`	401	The key has expired
`this API key is disabled`	401	The key has been disabled
`user quota is not enough`	403	Insufficient account balance; please top up
`token quota is not enough`	403	The key's remaining quota can't cover the pre-charge for this request
`This token has no access to model ...`	403	The key has a model allowlist that doesn't include this model
`Group specified in the request header is not available to this token`	403	The group in `X-Token-Group` isn't in the key's group list
`Your IP address is not in the token's allowed IP list`	403	The key has an IP allowlist
`The model ... is currently unavailable, please retry later`	503	Model name misspelled, the model isn't in the key's groups, or its routes are temporarily busy
`Upstream service unavailable (503)`	503	The upstream is temporarily unavailable; retry later
`Upstream rate limited (429)`	429	The upstream is rate limiting; retry later
`invalid request body: malformed JSON`	400	The request body is not valid JSON
`Upstream closed the stream without any output`	502	The upstream ended without returning anything (`code`: `upstream_empty_stream`); not billed, safe to retry
`... is not supported on this endpoint`	404	A Responses storage endpoint that is not supported was called (`code`: `unsupported_endpoint`); see Responses API
`Upstream capacity for the current group is saturated, please retry later`	429	The current group is at capacity when submitting a video task; retry later

When you see The model ... is currently unavailable, first check the model catalog to confirm the model name matches exactly (case-sensitive) and that the model is available in your key's groups.

Retry guidelines

Retry only 429 and 5xx; retrying 4xx won't succeed.
Use exponential backoff: 1 s, 2 s, 4 s… up to 3–5 attempts.
Failed requests are not billed, so retries never double-charge.