常见错误

先记录 HTTP 状态码、请求时间、接口路径和模型名称，再按下表排查。不要在截图或日志中公开完整密钥。

快速索引

状态码或现象	常见原因	首要检查
400	请求体或参数不兼容	只保留必填字段重试
401	密钥无效或鉴权头错误	密钥状态与请求头
403	IP、地区或安全策略限制	访问来源与密钥限制
404	Base URL 或接口路径错误	/v1 是否重复或缺失
413	请求体过大	上下文、图片和附件大小
429	余额、配额、并发或上游限流	使用记录与密钥限制
500	服务内部异常	稍后重试并记录请求时间
502/503/504	上游或网络链路异常	渠道状态与有限重试
流中途断开	上游连接或读取超时	网络、客户端超时和状态页

400 Bad Request

模型可能不支持某个采样字段、工具格式或消息类型。处理顺序：

1. 验证 JSON 格式。
2. 保留 model 和最小输入，删除可选参数。
3. 确认接口协议与请求体匹配。
4. 从 /v1/models 复制模型名称。

401 Unauthorized

• OpenAI 接口应使用 Authorization: Bearer sk-your-key。
• Anthropic 接口可使用 x-api-key: sk-your-key。
• 检查密钥是否已禁用、删除或过期。
• 检查复制时是否包含空格、引号或换行。

403 Forbidden

检查密钥 IP 白名单、黑名单和地区访问策略。网站页面的地区限制与 API 接口策略可能不同， 不要仅根据首页能否打开判断 API 是否可用。

404 Not Found

最常见原因是客户端自动追加路径：

错误示例：https://cloud.examplea.xyz/v1/v1/responses
正确示例：https://cloud.examplea.xyz/v1/responses

Codex CLI 的 base_url 填到 /v1；Claude Code 的 ANTHROPIC_BASE_URL 通常填写站点根地址，不手动追加 /v1/messages。

413 Payload Too Large

该错误表示请求体超过网关允许大小。缩短对话历史、压缩图片、拆分文件或改为分批处理。 只提高服务器限制不能解决模型本身的上下文窗口限制。

429 Too Many Requests

依次检查：

1. 账号余额是否充足。
2. 密钥配额和有效期。
3. 当前并发是否达到限制。
4. 上游是否正在限流。

客户端应指数退避，不能无间隔无限重试。

502、503、504

这类错误通常来自上游服务、代理链路或临时过载。等待数十秒后重试，并查看 渠道状态。持续发生时记录请求时间、模型、分组和状态码。