文档目录
错误码
每种状态码的含义、返回体长什么样、哪些该重试哪些不该，以及排查顺序。
接口返回非 2xx 状态码时，先对照下表。排查连通性时可以先用 curl 复现。
状态码速查
| 状态码 | 含义 | 怎么处理 | 能重试吗 |
|---|---|---|---|
400 | 请求格式或参数不正确 | 检查请求体 JSON、必填字段（如 model、messages、Anthropic 的 max_tokens）和接口路径是否匹配；提示见下面“400 的几种提示”。 | 不能，改好再发 |
401 | 密钥无效或已停用 | 确认密钥完整、没有多余空格，且在 API 密钥 页处于“启用”状态。 | 不能 |
402 | 余额不足 | 查看余额并充值，见 注册与充值。 | 充值后可以 |
403 | 没有访问该资源的权限 | 这把密钥或账号没有权限访问这个资源，请联系管理员。 | 不能 |
404 | 模型或接口路径不存在 | 模型名需与 模型定价 页完全一致；检查接入地址是否多带或少带了 /v1。 | 不能 |
413 | 请求体过大 | 缩短输入内容（上限 32MB）。 | 缩短后可以 |
429 | 触发并发或速率限制 | 降低并发和请求频率，稍等片刻后重试；客户端建议加指数退避。 | 可以，退避后 |
502 | 上游服务暂时不可用 | 系统已经尝试过备用线路但都没成功，稍后重试；持续出现可到 服务状态 页查看对应模型是否异常。 | 可以，退避后 |
503 | 服务暂时不可用 | 稍后重试；持续出现同样到服务状态页查看。 | 可以，退避后 |
返回体长什么样
OpenAI 格式（Chat Completions、Responses）：
OpenAI 格式
{"error": {"message": "账户余额不足，请充值后再试", "type": "insufficient_balance", "code": "insufficient_balance"}}Anthropic 格式（/v1/messages）：
Anthropic 格式
{"type": "error", "error": {"type": "insufficient_balance", "message": "账户余额不足，请充值后再试"}}程序里判断错误原因，看 code（OpenAI 格式）或 error.type（Anthropic 格式）比看状态码更准：
| code | 含义 |
|---|---|
invalid_api_key | 密钥无效或已停用 |
insufficient_balance | 余额不足 |
model_not_found | 模型不存在或当前不可用 |
rate_limited | 触发速率限制 |
request_too_large | 请求体过大 |
unsupported_endpoint | 这个系列的模型用错了接口格式 |
client_not_supported | 这个模型只接受 Claude Code / Claude Desktop 等官方客户端 |
client_version_too_old | 客户端版本太旧，需要升级 |
upstream_error | 上游暂时不可用（对应 502） |
service_unavailable | 服务暂时不可用（对应 503） |
400 的几种提示
- 不支持 xxx 接口：该系列的模型用错了接口格式，按提示改用对应接口，见 接口格式。
- 暂不支持 HTTP API 直连：这个模型的线路只接受 Claude Code / Claude Desktop 等官方客户端，请用官方客户端调用。
- 需要 Claude Code x.y.z 或更新版本：客户端版本太旧，升级即可。
排查顺序
选好模型，核对费用再接入
查看当前模型的价格与参数，用自己的输入、输出和缓存用量估算成本；遇到报错时按错误码排查。