Source: https://wiki.niceai.dev/guide/error-codes

# 常见错误码对照

NiceAI 兼容 OpenAI 与 Anthropic 协议，错误返回沿用这两种协议的格式：HTTP 状态码加一个 JSON 错误体，其中 `message` 字段会说明具体原因。排查时先看状态码，再看 `message`。

## 速查表

| 状态码 | 含义 | 常见原因 | 处理方法 |
| --- | --- | --- | --- |
| 400 | 请求参数错误 | 请求体格式不对、参数超出范围、上下文超过模型上限 | 按 `message` 修改请求；缩短上下文或降低 `max_tokens` |
| 401 | 认证失败 | 密钥错误、未填写、已删除或已禁用 | 重新复制密钥，检查请求头和客户端配置 |
| 403 | 无权访问 | 余额不足、密钥分组无权使用该模型、额度或权限受限 | 充值，或换用对应分组的密钥 |
| 404 | 地址或模型不存在 | Base URL 的 `/v1` 写错、模型名写错 | 见 [接口地址要不要加 /v1](https://wiki.niceai.dev/guide/v1-404)，核对模型名 |
| 429 | 请求过于频繁 | 短时间请求过多，或上游限流 | 降低并发，按指数退避重试 |
| 500 | 服务内部错误 | 服务端处理异常 | 稍后重试；持续出现时记录时间和请求信息反馈 |
| 502 | 网关错误 | 上游连接异常或返回了无效响应 | 稍后重试 |
| 503 | 服务暂不可用 | 当前分组暂时没有可用的上游、维护中 | 稍后重试，或换用其他分组 |
| 529 | 上游过载 | Anthropic 协议的 `overloaded_error`，模型侧负载过高 | 等待片刻后重试，降低并发 |

## 逐个说明

### 400 Bad Request

请求本身有问题，重试不会成功。常见情况：

- JSON 格式错误，或缺少 `model`、`messages` 等必填字段。
- 参数不被该模型支持，例如某些模型不支持特定的 `temperature` 范围或工具调用参数。
- 输入加输出超过了模型的上下文上限。可以缩短对话历史，或调小 `max_tokens`。

### 401 Unauthorized

认证没有通过：

- OpenAI 兼容协议使用请求头 `Authorization: Bearer 你的密钥`。
- Anthropic 协议使用 `x-api-key: 你的密钥`；Claude Code 通过 `ANTHROPIC_AUTH_TOKEN` 传入。
- 检查密钥前后是否带了空格或换行，以及在控制台「[API 密钥](https://niceai.dev/keys)」页面是否处于启用状态。

### 403 Forbidden

密钥有效，但这次请求不被允许：

- 账户余额不足，请先充值。
- 密钥所在分组不能使用该模型或该协议。例如 Claude Code 需要 Claude 分组的密钥，Codex 需要 OpenAI 分组的密钥。
- 密钥设置了额度或其他限制。

### 404 Not Found

绝大多数是接口地址拼错：Anthropic 协议不加 `/v1`，OpenAI 兼容协议加 `/v1`。另一种情况是模型名不存在，请以 [模型广场](https://niceai.dev/model-plaza) 的名称为准。

### 429 Too Many Requests

请求频率超过了限制，或者上游暂时限流。建议：

- 降低并发数，避免短时间内大量请求。
- 重试时使用指数退避，例如间隔 1 秒、2 秒、4 秒依次加长；响应头带有 `retry-after` 时按它等待。

### 500 / 502 / 503

服务端或上游的临时问题，一般重试即可恢复：

- **500**：服务内部错误。
- **502**：网关从上游拿到了无效响应，或连接中断。
- **503**：暂时没有可用的上游，或正在维护。

如果同一个错误持续几分钟以上，记下发生时间、模型名和错误信息，便于排查。

### 529 Overloaded

Anthropic 协议特有的状态码，表示模型侧负载过高（`overloaded_error`），与你的账户无关。等待片刻后重试即可，高峰期适当降低并发。

## 客户端里的重试设置

Claude Code、Codex 以及官方 SDK 一般都会对 429、5xx 自动重试几次。批量任务建议在代码里自行控制并发和重试次数，避免同时大量失败重试。

**排查顺序**
1. 用 curl 直接请求，排除客户端配置问题（示例见 [快速开始](https://wiki.niceai.dev/guide/quick-start)）。
2. 核对 Base URL、密钥、密钥分组和模型名。
3. 在控制台查看余额和使用记录。


## 下一步

- [接口地址要不要加 /v1](https://wiki.niceai.dev/guide/v1-404)
- [分组与倍率说明](https://wiki.niceai.dev/guide/billing-groups)
