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.

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

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.