常见错误
出错时先看 HTTP 状态码和错误码，再按下表处理。错误信息的语言跟随请求头 Accept-Language（zh-CN 或 en-US）。
错误格式
| 接口 | 格式 |
|---|---|
OpenAI 兼容 /v1/* |
{"error": {"message", "type", "code", "request_id"}} |
| Anthropic 兼容 | {"type": "error", "error": {"type", "message"}}，没有机器可读的错误码 |
| Gemini 兼容 | {"error": {"code", "message", "status"}} |
平台接口 /api/v1/*、媒体任务 |
{"code", "message", "request_id", "details"} |
联系支持时请附上 request_id。
常见错误码
| 错误码 | HTTP | 原因 | 处理 |
|---|---|---|---|
auth.invalid_key |
401 | 密钥错误、已暂停、已过期或已撤销；或把密钥放在了 URL 参数里 | 检查密钥和请求头 |
auth.forbidden |
403 | 模型不在这把密钥的可用模型里 | 修改密钥的可用模型 |
key.ip_denied |
403 | 来源 IP 不在密钥的白名单里 | 修改 IP 白名单 |
key.spend_limit |
402 | 达到密钥的每日或每月消费上限（OpenAI 格式为 billing.key_limit_exceeded） |
调高上限或等待周期切换 |
billing.insufficient_credit |
402 | 余额不足以覆盖这次调用的预估费用 | 充值 |
billing.in_arrears |
403 | 账户欠费 | 充值补足欠费 |
rate.limited |
429 | 请求速率超限 | 退避后重试 |
concurrency.exceeded |
429 | 同时进行的请求数超限 | 等待进行中的请求结束 |
model.unavailable |
404 | 模型不存在、维护中、已下架，或不具备这个接口需要的能力 | 核对模型 ID 与模型能力 |
routing.not_applied |
409 | 模型暂时没有可用的供应线路 | 稍后重试或换用其他模型 |
upstream.unavailable |
503 | 上游服务出错或超时 | 稍后重试，失败的调用不收费 |
account.restricted |
403 | 账户的 API 调用被暂停 | 查看站内通知或提交工单 |
content.prohibited.* |
403 | 请求内容命中内容规则 | 修改内容，如有异议可按 details 里的链接申诉 |
重试建议
- 429 和 503 可以重试，建议指数退避并设置最大次数。
- 401、402、403、404 重试不会成功，需要先按上表处理。
- 非流式请求整体超时为 120 秒，长输出建议使用流式。
常见问题
- 返回 429 应该怎么重试？
- rate.limited 和 concurrency.exceeded 都可以重试，建议指数退避并设置最大重试次数，同时减少并发请求。
- upstream.unavailable 会扣费吗？
- 不会。上游出错或超时的调用按失败处理，不收费，可以稍后重试。
- Anthropic 格式为什么看不到错误码？
- Anthropic 协议的错误体只有类型和信息，没有机器可读的错误码；需要精确判断时可以改用 OpenAI 兼容接口。