# 错误码与错误响应

> BigModel.io 全部错误码的 HTTP 状态、含义和解决方法，四种错误响应格式，流式过程中的错误，X-Request-ID，以及联系支持时需要提供的信息。

网页版: https://bigmodel.io/zh-cn/docs/errors · 更新于 2026-10-18

错误来自两处：路由之前的 Key 校验，以及端点处理逻辑（或其背后的模型供应商）。两者的响应体格式不同，所以先看 HTTP 状态码，再看错误码或类型。

| 状态码 | 常见原因 | 是否重试 |
|---|---|---|
| 400 | 请求格式错误 | 否，修正请求 |
| 401 | Key 缺失、错误或已停用 | 否 |
| 402 | 视频：余额不足以预扣 | 充值后 |
| 403 | 余额、过期、IP 规则、分组或权限 | 否 |
| 404 | Key 所在分组不提供该端点 | 否 |
| 409 | 对话历史无法被模型接受；视频幂等冲突 | 否 |
| 413 | 请求体过大 | 否 |
| 429 | 触发限制（见 [限额与速率](https://bigmodel.io/zh-cn/docs/rate-limits)） | 视错误码而定 |
| 502 / 503 | 上游失败、无可用容量或模型未提供 | 502、过载：是；模型未提供：否 |

## 错误格式

### Key 校验

Key、账户、余额、额度或套餐问题会在路由前被拦截，所有端点都返回扁平结构：

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

### Anthropic 格式

`/v1/messages`、`/v1/messages/count_tokens`、仅 Chat Completions 分组的 404 以及缺少分组的 403 使用 Anthropic 结构：

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

### OpenAI 格式

OpenAI 分组上的 `/v1/chat/completions` 和 `/v1/responses` 使用 OpenAI 结构：

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

Anthropic 分组上的 `/v1/responses` 返回 `{"error": {"code": "...", "message": "..."}}`。

### 视频格式

`/v1/videos` 系列端点返回 `{"error": {"type": "<code>", "message": "..."}}`，其中 `type` 是下文的视频错误码之一。

稳妥的客户端依次读取 `code`、`error.type`、`error.code`，都没有时再按 HTTP 状态码处理。

## Key 与账户错误

以下错误使用扁平格式。

| HTTP | `code` | 含义 | 解决方法 |
|---|---|---|---|
| 400 | `api_key_in_query_deprecated` | Key 放在 `?key=` 或 `?api_key=` 中 | 改用 `Authorization: Bearer` 或 `x-api-key` |
| 401 | `API_KEY_REQUIRED` | 请求中没有 Key | 添加请求头，确认环境变量已设置 |
| 401 | `INVALID_API_KEY` | Key 无法识别 | 从 [API Keys](https://bigmodel.io/keys) 重新复制 |
| 401 | `API_KEY_DISABLED` | Key 已停用 | 在 API Keys 中启用 |
| 401 | `USER_NOT_FOUND` | Key 所属账户不存在 | 联系 [支持](https://bigmodel.io/support) |
| 401 | `USER_INACTIVE` | 账户未启用 | 联系支持 |
| 403 | `ACCESS_DENIED` | 被 Key 的 IP 白名单 / 黑名单拦截 | 检查 Key 的 IP 规则 |
| 403 | `API_KEY_EXPIRED` | Key 已过有效期 | 延长有效期或新建 Key |
| 403 | `INSUFFICIENT_BALANCE` | 余额为 0 或已为负 | [充值](https://bigmodel.io/purchase) |
| 403 | `SUBSCRIPTION_NOT_FOUND` | Key 属于套餐分组，但没有有效套餐 | 购买套餐，或改用按余额计费的分组 |
| 403 | `SUBSCRIPTION_INVALID` | 套餐对本次请求无效 | 在控制台检查套餐 |
| 429 | `API_KEY_QUOTA_EXHAUSTED` | Key 的美元额度已用完 | 提高或重置额度 |
| 429 | `USAGE_LIMIT_EXCEEDED` | 套餐每日、每周或每月限额已用完 | 等待下一个周期 |

## 请求与路由错误

以下错误使用对应端点的 Anthropic 或 OpenAI 格式，表中为 `error.type` 的值。

| HTTP | `error.type` | 典型信息 | 解决方法 |
|---|---|---|---|
| 400 | `invalid_request_error` | JSON 无效、请求体为空、“model is required”、`stream` 类型错误 | 修正请求体 |
| 400 | `invalid_request_error` | HTTP 方式不支持 `previous_response_id` | 每轮发送完整 `input`（或使用 WebSocket） |
| 402 | `spend_cap_reached` | “weekly spend cap reached” / “monthly spend cap reached”；`Retry-After` 指向重置时间 | 等待重置，或在[余额与账单](https://bigmodel.io/purchase)调整上限 |
| 403 | `billing_error` | “insufficient balance: top up to use this model, or call a free model …” | [充值](https://bigmodel.io/purchase)，或调用标价 $0 的模型 |
| 403 | `permission_error` | “API Key is not assigned to any group” | 给 Key 分配分组 |
| 403 | `permission_error` | “This group does not allow /v1/messages dispatch” | 改用 Chat Completions 或其他分组 |
| 403 | `content_policy_violation` | 请求被内容审核拦截 | 修改输入 |
| 404 | `not_found_error` | “`<Name>` platform only supports /v1/chat/completions; /v1/messages is not available” | 改用 `/v1/chat/completions`，或换用提供该端点的分组的 Key |
| 409 | `malformed_session_state` | 历史中的思考块或工具调用 ID 无效 | 原样回传历史，或删除出错的轮次 |
| 413 | | 请求体过大（上限 256 MiB） | 减小输入 |
| 429 | `rate_limit_exceeded` | RPM 限制，带 `Retry-After` | 等待 `Retry-After` 秒 |
| 429 | `rate_limit_exceeded` | “free-model rate limit reached”（余额为 0）；带 `Retry-After` | 等待，或充值解除限制 |
| 429 | `rate_limit_exceeded` | “api key 5小时限额已用完”/“日限额”/“7天限额” | 等待窗口重置或提高上限 |
| 429 | `rate_limit_error` | “Too many pending requests”/“Concurrency limit exceeded for user” | 减少并行请求，退避重试 |
| 429 | `rate_limit_error` | 供应商限流 | 退避重试 |
| 502 | `upstream_error` | “Upstream request failed” | 退避重试 |
| 503 | `api_error` | “No available accounts: no available accounts supporting model: X” | 模型 ID 错误或不在 Key 的分组中，从 [/models](https://bigmodel.io/zh-cn/models) 复制 |
| 503 | `api_error` | “No available channels”/“Request pricing is not available” | 模型暂不可售，换模型或稍后再试 |
| 503 | `billing_service_error` | 计费检查失败 | 稍后重试 |
| 503 | `overloaded_error` | 供应商过载 | 退避重试 |

文本模型没有 404“model not found”：未知或分组未提供的模型返回上面的 503 `No available accounts`。可以用 `GET /v1/models` 核对。

## 图片、视频与音频错误

| HTTP | `error.type` | 含义 | 解决方法 |
|---|---|---|---|
| 400 | `invalid_request_error` | 参数错误，或输入文件读不到 | 对照模型页检查请求体；输入用公开 URL 或 data URI，单个不超过 50 MB |
| 402 | `insufficient_balance` | 余额不足以覆盖本次估价加上未完成的任务 | 充值 |
| 403 | `permission_error` | 套餐 Key 不能调用多模态模型 | 改用按量付费的 Key |
| 404 | `model_not_available` | 该 Key 或该接口不提供这个模型 | 从 `GET /v1/models` 选择模型 |
| 404 | `not_found_error` | 账户下找不到这个任务 ID | 检查 ID |
| 429 | `rate_limit_error` | 未完成的任务或工作流太多 | 等部分完成后再提交 |
| 503 | `api_error` | 生成服务暂时不可用 | 稍后重试 |

见 [多模态任务 API 参考](https://bigmodel.io/zh-cn/docs/api-media-tasks)。

## 流式过程中的错误

流开始后 HTTP 状态已经是 200，因此错误以 SSE 事件的形式发送，随后关闭流：

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

以上是 OpenAI 协议的形式。在 `/v1/messages` 上，错误是一行 Anthropic 结构的 `data:`：`data: {"type":"error","error":{"type":"...","message":"..."}}`。收到 `error` 事件应视为请求失败：不要把已收到的部分输出当成完整结果，类型可重试时再重试。见 [流式输出](https://bigmodel.io/zh-cn/docs/streaming)。

## X-Request-ID

每个响应都带有 `X-Request-ID` 响应头。如果你自己发送了 `X-Request-ID`，会原样返回，方便关联日志。部分模型的响应中，它会是模型供应商的请求 ID。由于 CORS 未暴露该响应头，浏览器读不到它；请从服务端调用 API。

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

## 联系支持

打开 [支持](https://bigmodel.io/support)（或发邮件到 support@bigmodel.io），并附上：

- `X-Request-ID` 和请求时间（含时区）
- 端点和模型 ID
- HTTP 状态码和完整错误响应体
- 是否为流式请求
- 使用的 SDK 或工具及版本

请先移除 API Key、`Authorization` 请求头和敏感的提示内容。失败请求的请求体会在去除凭据后保留最多 30 天，因此近期的请求 ID 可以追查；见 [数据与隐私](https://bigmodel.io/zh-cn/docs/data-privacy)。

## 常见问题排查

**所有请求都返回 503 `No available accounts`。** 模型 ID 拼错（注意大小写和点号：`deepseek-v4-pro`，不是 `DeepSeek-V4-Pro`），或模型属于其他分组。

**刚创建 Key 就返回 401。** 环境变量或工具设置里还是旧 Key。打印前几位和控制台对比。

**Agent 中出现 409 `malformed_session_state`。** 客户端修改或重排了历史中的思考块或工具块。新开会话，或关闭会改写这些块的历史压缩功能。

## 相关文档

- [限额与速率](https://bigmodel.io/zh-cn/docs/rate-limits)
- [认证与 API Key](https://bigmodel.io/zh-cn/docs/authentication)
- [计费与充值](https://bigmodel.io/zh-cn/docs/billing)
- [状态页](https://bigmodel.io/zh-cn/status)