外观
常见错误码对照
NiceAI 兼容 OpenAI 与 Anthropic 协议,错误返回沿用这两种协议的格式:HTTP 状态码加一个 JSON 错误体,其中 message 字段会说明具体原因。排查时先看状态码,再看 message。
速查表
| 状态码 | 含义 | 常见原因 | 处理方法 |
|---|---|---|---|
| 400 | 请求参数错误 | 请求体格式不对、参数超出范围、上下文超过模型上限 | 按 message 修改请求;缩短上下文或降低 max_tokens |
| 401 | 认证失败 | 密钥错误、未填写、已删除或已禁用 | 重新复制密钥,检查请求头和客户端配置 |
| 403 | 无权访问 | 余额不足、密钥分组无权使用该模型、额度或权限受限 | 充值,或换用对应分组的密钥 |
| 404 | 地址或模型不存在 | Base URL 的 /v1 写错、模型名写错 | 见 接口地址要不要加 /v1,核对模型名 |
| 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 密钥」页面是否处于启用状态。
403 Forbidden
密钥有效,但这次请求不被允许:
- 账户余额不足,请先充值。
- 密钥所在分组不能使用该模型或该协议。例如 Claude Code 需要 Claude 分组的密钥,Codex 需要 OpenAI 分组的密钥。
- 密钥设置了额度或其他限制。
404 Not Found
绝大多数是接口地址拼错:Anthropic 协议不加 /v1,OpenAI 兼容协议加 /v1。另一种情况是模型名不存在,请以 模型广场 的名称为准。
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 自动重试几次。批量任务建议在代码里自行控制并发和重试次数,避免同时大量失败重试。
排查顺序
- 用 curl 直接请求,排除客户端配置问题(示例见 快速开始)。
- 核对 Base URL、密钥、密钥分组和模型名。
- 在控制台查看余额和使用记录。