算汇开发者文档
错误处理与排查
按 HTTP 状态码排查 API 密钥、请求参数、余额、限流与上游服务错误。
本页内容
先记录 HTTP 状态码和响应中的错误消息，再按下面顺序排查。不要只截取“请求失败”一行，也不要把完整 API 密钥发给任何人。
常见状态码
| 状态码 | 常见原因 | 建议处理 |
|---|---|---|
400 | JSON 无效、缺少必填字段、参数不受模型支持 | 对照接口文档缩减为最小请求，再逐项加回参数 |
401 | 密钥缺失、错误、停用或过期 | 检查 Bearer 请求头与密钥状态 |
402 | 账户余额不足以完成请求前的额度预扣 | 充值后再请求；余额不足是确定性错误，不要自动重试 |
403 | 密钥无权使用目标模型，或密钥消费上限不足 | 查询 /v1/models，并检查密钥的模型范围与消费上限 |
429 | 请求频率超过账号的速率上限 | 按响应头 Retry-After 等待后重试，并降低并发；详见下方“速率限制” |
5xx | 平台或上游暂时异常 | 保留时间、模型和错误消息，有限重试或切换备用模型 |
最小化排查法
- 用同一密钥请求
/v1/models，确认鉴权和网络正常； - 将请求体缩减为
model与一条user消息； - 在控制台「在线体验」尝试同一模型；
- 检查账户余额、密钥有效期和消费上限；
- 记录请求时间、接口路径、模型、状态码和完整错误消息后联系支持。
速率限制
速率上限按账号计算，名下所有 API 密钥共用同一份配额——把调用拆到多把密钥不会提高总的请求速率。当前上限和已用比例显示在控制台概览。
账号自身的速率上限被触发时返回 429，并带上这些响应头：
| 响应头 | 含义 |
|---|---|
Retry-After | 建议等待的秒数 |
X-RateLimit-Limit-Requests | 账号每分钟的请求上限 |
X-RateLimit-Remaining-Requests | 拒绝瞬间的剩余额度（固定为 0） |
X-RateLimit-Reset-Requests | 额度恢复所需时间 |
官方 OpenAI SDK 会自动读取 Retry-After 并据此退避，通常无需自行处理。自建重试逻辑时优先读这个头，不要用固定的等待时间。
需要更高速率请通过获取支持联系我们，说明预期的每分钟请求数与业务场景。
是否应该重试
网络中断、超时、429 和部分 5xx 可以有限重试，并使用指数退避与随机抖动。请求参数错误、鉴权失败、余额不足等确定性问题，必须先修正原因，不应自动重试。
429 的正确重试方式是先检查是否有 Retry-After 头：有则等待相应秒数，无则按指数退避重试。固定间隔在低速率档位上会连续撞墙，因为那一档要等整个窗口结束才释放额度。