# Error codes and responses

> Every BigModel.io error code with its HTTP status, meaning and fix, the four error body formats, streaming errors, X-Request-ID and what to send to support.

Web version: https://bigmodel.io/docs/errors · Updated 2026-10-18

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.

| Status | Usual cause | Retry? |
|---|---|---|
| 400 | Malformed request | No, fix the request |
| 401 | Missing, wrong or disabled key | No |
| 402 | Video: balance cannot cover the hold | After top-up |
| 403 | Balance, expiry, IP rule, group or permission | No |
| 404 | Endpoint not served by the key's group | No |
| 409 | Conversation history the model cannot accept; video idempotency conflict | No |
| 413 | Request body too large | No |
| 429 | Limit hit (see [Limits & rate limits](https://bigmodel.io/docs/rate-limits)) | Depends on the code |
| 502 / 503 | Upstream failure, no capacity, or model not served | 502, overload: yes; model not served: no |

## 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:

```json
{ "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:

```json
{ "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:

```json
{ "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.

| HTTP | `code` | Meaning | Fix |
|---|---|---|---|
| 400 | `api_key_in_query_deprecated` | Key sent as `?key=` or `?api_key=` | Send it in `Authorization: Bearer` or `x-api-key` |
| 401 | `API_KEY_REQUIRED` | No key in the request | Add the header; check the env var is set |
| 401 | `INVALID_API_KEY` | Key not recognised | Copy it again from [API Keys](https://bigmodel.io/keys) |
| 401 | `API_KEY_DISABLED` | Key is disabled | Enable it in API Keys |
| 401 | `USER_NOT_FOUND` | Key's account does not exist | Contact [Support](https://bigmodel.io/support) |
| 401 | `USER_INACTIVE` | Account is not active | Contact Support |
| 403 | `ACCESS_DENIED` | Blocked by the key's IP whitelist / blacklist | Check the key's IP rules |
| 403 | `API_KEY_EXPIRED` | Key passed its expiry date | Extend the expiry or create a new key |
| 403 | `INSUFFICIENT_BALANCE` | Balance is zero or below | [Top up](https://bigmodel.io/purchase) |
| 403 | `SUBSCRIPTION_NOT_FOUND` | Key's group is a plan group and you have no active plan | Buy a plan, or use a balance-billed group |
| 403 | `SUBSCRIPTION_INVALID` | Plan is not valid for this request | Check the plan in the console |
| 429 | `API_KEY_QUOTA_EXHAUSTED` | Key's USD quota is used up | Raise or reset the quota |
| 429 | `USAGE_LIMIT_EXCEEDED` | Plan's daily, weekly or monthly limit reached | Wait for the next period |

## Request and routing errors

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

| HTTP | `error.type` | Typical message | Fix |
|---|---|---|---|
| 400 | `invalid_request_error` | Invalid JSON, empty body, "model is required", invalid `stream` | Fix the request body |
| 400 | `invalid_request_error` | `previous_response_id` is not supported over HTTP | Send the full `input` each turn (or use the WebSocket) |
| 402 | `spend_cap_reached` | "weekly spend cap reached" / "monthly spend cap reached"; `Retry-After` until the reset | Wait for the reset or change the cap on [Balance & billing](https://bigmodel.io/purchase) |
| 403 | `billing_error` | "insufficient balance: top up to use this model, or call a free model …" | [Top up](https://bigmodel.io/purchase), or call a model priced at $0 |
| 403 | `permission_error` | "API Key is not assigned to any group" | Assign a group to the key |
| 403 | `permission_error` | "This group does not allow /v1/messages dispatch" | Use Chat Completions or another group |
| 403 | `content_policy_violation` | Request blocked by moderation | Change the input |
| 404 | `not_found_error` | "`<Name>` platform only supports /v1/chat/completions; /v1/messages is not available" | Use `/v1/chat/completions`, or a key from a group that serves the endpoint |
| 409 | `malformed_session_state` | Thinking blocks or tool call IDs in the history are invalid | Resend history unmodified, or drop the broken turns |
| 413 | | Request body too large (limit 256 MiB) | Send smaller inputs |
| 429 | `rate_limit_exceeded` | RPM limit; has `Retry-After` | Wait `Retry-After` seconds |
| 429 | `rate_limit_exceeded` | "free-model rate limit reached" (zero balance); has `Retry-After` | Wait, or top up to remove the limit |
| 429 | `rate_limit_exceeded` | "api key 5小时限额已用完" / "日限额" / "7天限额" | Wait for the window reset or raise it |
| 429 | `rate_limit_error` | "Too many pending requests" / "Concurrency limit exceeded for user" | Reduce parallel requests, retry with backoff |
| 429 | `rate_limit_error` | Provider rate limit | Retry with backoff |
| 502 | `upstream_error` | "Upstream request failed" | Retry with backoff |
| 503 | `api_error` | "No available accounts: no available accounts supporting model: X" | Model ID is wrong or not in the key's group. Copy it from [/models](https://bigmodel.io/models) |
| 503 | `api_error` | "No available channels" / "Request pricing is not available" | Model temporarily not sellable. Try another model or later |
| 503 | `billing_service_error` | Billing check failed | Retry later |
| 503 | `overloaded_error` | Provider overloaded | Retry with backoff |

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

| HTTP | `error.type` | Meaning | Fix |
|---|---|---|---|
| 400 | `invalid_request_error` | Bad parameters or an input that can't be read | Check the body against the model's page; inputs are public URLs or data URIs up to 50 MB |
| 402 | `insufficient_balance` | Balance can't cover the estimate plus unfinished tasks | Top up |
| 403 | `permission_error` | Plan keys can't use media models | Use a pay-as-you-go key |
| 404 | `model_not_available` | The model isn't served for this key or endpoint | Pick a model from `GET /v1/models` |
| 404 | `not_found_error` | Task ID not found for this account | Check the ID |
| 429 | `rate_limit_error` | Too many unfinished tasks or workflows | Wait for some to finish |
| 503 | `api_error` | Generation is temporarily unavailable | Retry later |

See [Media task API reference](https://bigmodel.io/docs/api-media-tasks).

## 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:

```text
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](https://bigmodel.io/docs/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.

```bash
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](https://bigmodel.io/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](https://bigmodel.io/docs/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](https://bigmodel.io/docs/rate-limits)
- [Authentication](https://bigmodel.io/docs/authentication)
- [Billing & top-ups](https://bigmodel.io/docs/billing)
- [Status page](https://bigmodel.io/status)