Error codes and responses

Errors come from two places: the key check that runs before routing, and the endpoint handler (or the model provider behind it). Each uses its own body format, so parse the HTTP status first, then the code or type.

#Error formats

#Key checks

Problems with the key, account, balance, quota or plan are caught before routing and return a flat body on every endpoint:

{ "code": "INVALID_API_KEY", "message": "Invalid API key" }

#Anthropic format

/v1/messages, /v1/messages/count_tokens, the Chat-Completions-only 404s and the missing-group 403 use the Anthropic shape:

{ "type": "error", "error": { "type": "rate_limit_error", "message": "Too many pending requests, please retry later" } }

#OpenAI format

/v1/chat/completions and /v1/responses on OpenAI groups use the OpenAI shape:

{ "error": { "type": "api_error", "message": "No available accounts: no available accounts supporting model: glm-5.4" } }

/v1/responses on Anthropic groups returns {"error": {"code": "...", "message": "..."}}.

#Video format

The /v1/videos endpoints return {"error": {"type": "<code>", "message": "..."}}, where type is one of the video codes below.

A robust client reads code, then error.type, then error.code, and falls back to the HTTP status.

#Key and account errors

These use the flat format.

#Request and routing errors

These use the Anthropic or OpenAI format of the endpoint. The value shown is error.type.

There is no 404 "model not found" for text models: an unknown or unserved model returns the 503 No available accounts error above. Check with GET /v1/models.

#Image, video and audio errors

See Media task API reference.

#Errors during streaming

Once a stream has started, the HTTP status is already 200, so errors arrive as an SSE event and the stream closes:

event: error
data: {"error":{"type":"upstream_error","message":"Upstream request failed"}}

That is the OpenAI-protocol form. On /v1/messages the error is a data: line in the Anthropic shape, data: {"type":"error","error":{"type":"...","message":"..."}}. Treat an error event as a failed request: do not use the partial output as complete, and retry if the type is retryable. See Streaming.

#X-Request-ID

Every response carries an X-Request-ID header. If you send your own X-Request-ID, it is echoed back, which lets you correlate logs. For some models it carries the model provider's request ID instead. Browsers cannot read this header because CORS does not expose it; call the API from your server.

curl -sD - -o /dev/null https://bigmodel.io/v1/models \
  -H "Authorization: Bearer $BIGMODEL_API_KEY" | grep -i x-request-id

#Contacting support

Open Support (or email support@bigmodel.io) and include:

• X-Request-ID and the time of the request, with timezone
• Endpoint and model ID
• HTTP status and the full error body
• Whether the request was streaming
• The SDK or tool and its version

Remove your API key, Authorization headers and any sensitive prompt content first. Bodies of failed requests are kept up to 30 days with credentials removed, so recent request IDs can be traced; see Data & privacy.

#Troubleshooting

Every request returns 503 No available accounts. The model ID is misspelled (check case and dots: deepseek-v4-pro, not DeepSeek-V4-Pro), or it belongs to another group.

401 right after creating a key. The old key is still in the environment or tool settings. Print the first characters to compare with the console.

409 malformed_session_state in an agent. Your client edited or reordered thinking or tool blocks in the history. Start a new session or disable history compaction that rewrites these blocks.

#Related

• Limits & rate limits
• Authentication
• Billing & top-ups
• Status page