Skip to content

常见错误码对照 ​

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 自动重试几次。批量任务建议在代码里自行控制并发和重试次数,避免同时大量失败重试。

排查顺序

  1. 用 curl 直接请求,排除客户端配置问题(示例见 快速开始)。
  2. 核对 Base URL、密钥、密钥分组和模型名。
  3. 在控制台查看余额和使用记录。

下一步 ​

NiceAI · 稳定的 AI 大模型 API 中转站