直接答案：AI API 报错应先保留状态码、响应正文和请求 ID，再按地址、认证、模型权限、额度与上游状态依次排查。401/403 多与密钥和权限有关，429 多与速率或额度有关，5xx 才优先考虑服务链路。
1. 五分钟快速排查顺序
- 确认请求地址使用
https://www.codex789.com/v1，且没有重复拼接/v1。 - 确认请求头为
Authorization: Bearer YOUR_API_KEY。 - 从模型广场或 API 密钥页面重新复制完整模型代号。
- 检查账户余额、密钥额度、有效期和模型分组。
- 记录状态码、响应正文、请求 ID、发生时间和模型代号。
先保留原始错误不要只记录“调用失败”。响应正文和请求 ID 往往是定位问题的关键。
2. 常见 AI API 错误码对照表
| 状态码 | 常见原因 | 优先处理 |
|---|---|---|
| 400 | JSON、参数或消息格式错误 | 缩小到最小请求并核对字段 |
| 401 | API Key 缺失、无效或格式错误 | 检查 Bearer 请求头与密钥状态 |
| 403 | 密钥或分组无模型权限 | 核对密钥分组和模型访问范围 |
| 404 | 路径或模型代号不存在 | 检查 Base URL、接口路径和模型名 |
| 429 | 请求过快、并发过高或额度不足 | 降并发、查额度、按退避策略重试 |
| 500 | 请求处理内部异常 | 保存请求 ID，简化请求后重试 |
| 502 | 网关未获得有效上游响应 | 短次数重试或切换备用模型 |
| 503 | 服务临时繁忙或维护 | 延迟重试，避免持续高频请求 |
| 504 | 上游响应超时 | 检查输入长度并提高合理超时 |
3. 401 与 403：认证和权限问题
401 Unauthorized
- 请求头缺少
Bearer前缀。 - API Key 前后包含空格、引号或换行。
- 密钥已删除、过期或复制不完整。
- 密钥与当前 Base URL 不属于同一环境。
403 Forbidden
认证可能已经通过，但密钥分组没有目标模型权限。重新创建密钥时，确认分组包含准备调用的模型，并以创建密钥页面显示的代号为准。若响应包含 Invalid prompt 或 usage policy 提示，应按提示词策略拦截排查检查输入内容，而不是反复更换密钥。
4. 429：请求频率、并发或额度受限
429 不只代表“请求太快”，还可能来自账户余额、密钥额度、模型并发或上游速率约束。DeepSeek 调用可结合TPM 限流与 429 排查确认 Token 速率是否超限。
- 将突发批量请求改为队列，平滑发送。
- 读取响应中的
Retry-After，存在时优先遵循。 - 使用指数退避，例如 1 秒、2 秒、4 秒，并限制最大次数。
- 按项目拆分密钥，避免多个应用争用同一额度。
- 核对模型倍率和余额，参阅Token 与模型倍率说明。
5. 500、502、503、504：服务与线路异常
5xx 错误通常不是修改 API Key 能解决的问题。先用更短输入和同一模型发送最小请求，确认是否与请求体大小相关。
- 偶发错误：最多进行少量指数退避重试。
- 连续错误：暂停该模型并切换同类备用模型。
- 长请求超时：减少上下文，使用流式输出，并设置合理的完整响应超时。
- 持续异常：将请求 ID、发生时间、模型代号和响应正文提供给客服微信 GPT774。
有关成功率、延迟和线路切换，请查看AI API 中转站稳定性指南。
6. 提交问题时应保留哪些信息
| 需要保留 | 不应提交 |
|---|---|
| 请求时间、状态码、请求 ID | 完整 API Key |
| 模型代号、接口路径、SDK 版本 | 用户隐私和未脱敏业务数据 |
| 脱敏后的请求参数与响应正文 | 包含密钥的终端截图 |
7. 常见问题
GPT API 返回 429 怎么处理？
检查余额、密钥额度、模型并发和速率，降低并发后按 Retry-After 或指数退避重试。
API 返回 401 但密钥看起来正确怎么办？
重新复制密钥，确认没有换行，并检查 Authorization、Base URL 和密钥有效期。
502 和 503 可以一直重试吗？
应限制重试次数。持续失败时切换备用模型或稍后重试，避免请求堆积。