AI API 报错排查：401、403、404 与 429 怎么处理
遇到请求失败，先保存状态码和错误正文，再判断是否重试。相同的 HTTP 状态可能对应不同原因，尤其不能把所有 429 都当作短暂限流。
零词元··约 5 分钟阅读先记住这一点
先看状态码，再看错误 code 和 message。401 检查鉴权，403 检查权限与余额，429 要先区分额度耗尽和临时限流。
本文目录
1. 收集最少但有效的排查信息
记录请求时间、接口路径、模型 ID、HTTP 状态以及错误正文中的 code、type 和 message。如果响应头包含请求 ID，也一并保存。本站文档提到 X-Client-Request-ID；实际响应也可能带有 X-Request-ID，以收到的响应为准。
向支持人员反馈时，隐藏 Authorization、API Key、个人信息和业务提示内容。可以保留经过脱敏的最小请求体，帮助复现参数或协议问题。
2. 按状态码缩小范围
| 状态 | 优先检查 | 下一步 |
|---|---|---|
| 400 | 参数、JSON 格式、协议 | 按 message 修正请求，不原样连续重试。 |
| 401 | 密钥缺失、无效、停用或账户停用 | 检查 Bearer 请求头和密钥状态。 |
| 403 | 有效期、IP 限制、余额、分组或订阅权限 | 结合错误码修复对应权限或额度。 |
| 404 | 路径、模型 ID 与分组支持范围 | 查询当前密钥模型列表并核对接口协议。 |
| 429 | 总额度、时间窗口额度、频率或并发 | 先区分额度用尽与临时限流。 |
| 500 / 502 / 503 | 服务或上游暂时异常 | 限制次数地退避重试，持续失败时记录请求 ID。 |
3. 特别区分三类 429
API_KEY_QUOTA_EXHAUSTED或insufficient_quota：密钥额度耗尽。等待几秒通常无效，需检查额度配置。API_KEY_RATE_5H_EXCEEDED等窗口额度错误：检查相应时间窗口，等窗口重置或调整额度。rate_limit_error：可能超过调用频率或并发限制，先降低并发，再按响应提示退避。
如果出现 INVALID_AUTH_RATE_LIMITED，先停止使用无效密钥重复请求，修复鉴权后再测试。
4. 设置有上限的重试
对可恢复的临时错误，可采用逐步延长的等待时间，并加入随机抖动，避免多个请求同时再次涌入。如果响应给出 Retry-After，优先遵循它。设置最大尝试次数和总超时，不要无限循环。
网络超时不等于服务端没有执行请求。需要触发工具或业务动作的请求，应单独设计去重机制。流式响应已返回部分内容时，不要把一次重试的输出直接拼接到原来的内容后面。
5. 用一次最小请求复核
常见问题
429 都可以等待几秒后重试吗？
不可以。额度耗尽需要调整额度或等待指定窗口重置；频率或并发限制才适合降低并发并退避重试。
请求超时能证明没有扣费或没有执行吗？
不能。客户端超时不能证明服务端未完成处理。请检查请求 ID、用量记录和业务动作状态；不要据此无条件重复提交。
反馈故障需要提供完整密钥吗？
不需要，也不应提供。使用请求时间、接口路径、模型 ID、脱敏错误正文和响应中的请求 ID 即可开始排查。
准备好开始验证了吗？
使用已有账号进入控制台，确认密钥权限与可用额度，再执行最小请求。
登录控制台 查看文档