AI API 错误排查：401、403、429 与 5xx
按鉴权、访问策略、限流、客户端取消与上游故障分层诊断 AI API 错误，并判断何时可以安全重试。
诊断 AI API 错误时，状态码只是调查入口，不是完整结论。重试前应保存请求 ID、UTC 时间、端点、模型、API Key 名称、所选分组、结构化错误与关键时序，先判断请求在哪一层被拒绝或中断。
常见层级包括客户端、鉴权、访问策略、协议校验、路由、模型后端以及下游连接。按顺序排查，能避免把 Key 权限问题误判为渠道故障，也能避免无边界重试继续增加成本。
常见状态码如何理解
| 状态码 | 优先判断 | 第一项动作 |
|---|---|---|
| 400 | 请求结构、字段或协议不合法 | 对照当前端点修正请求，不要原样重试 |
| 401 | 凭据缺失、格式错误、失效或过期 | 检查 Authorization Header 与当前 Key |
| 403 | 已鉴权，但被账号、模型、分组、IP 或策略拒绝 | 先检查 Key 限制与访问范围 |
| 404 | 端点路径或模型标识不正确 | 核对 Base URL、路径和模型列表 |
| 429 | 请求速率、额度或可用路由达到限制 | 查明限制归属，再做有界退避或回退 |
| 499 | 下游客户端在完成前断开或取消 | 检查调用方超时、Abort、代理和首个有效输出 |
| 500 | 内部处理或适配失败 | 保留请求 ID，仅在重复执行安全时重试 |
| 502/503 | 上游响应异常、路由不可用或暂时容量不足 | 查看路由证据，有限次回退或重试 |
| 504 | 网关或上游时间预算耗尽 | 对比首输出、总耗时与各层 Deadline |
具体请求仍应以错误体和请求记录为准。
401：先核对凭据
401 通常发生在有效模型路由之前。确认 Header 使用 Authorization: Bearer ...，没有引号、空格或占位值；Key 已启用且未过期；请求发往正确的 Modelflare Host；部署或 Secret Manager 没有继续使用轮换前的旧 Key。
不要把完整 Key 写进日志、工单或截图。如果怀疑泄露，应创建替代 Key、切换工作负载并撤销旧凭据。
403：优先看访问策略
鉴权成功并不代表请求一定能进入渠道。以下情况都可能在选择渠道前返回 403：
- Key 不允许请求的模型；
- IP 白名单不包含 Modelflare 实际观察到的客户端 IP；
- 账号无权使用目标模型分组；
- 用户或 Key 已被策略禁用；
- 所需能力不被该路由允许。
应使用同一 Key 获取 /v1/models，检查分组、模型限制和精确错误码。若请求尚未选中渠道，更换上游渠道无法修复前置策略拒绝。
429：避免制造重试风暴
429 是容量或策略信号，不是立即无限重试的指令。先确认限制来自 Key 额度、账号、模型分组还是具体路由。允许重试时，应遵循 Retry-After，使用带抖动的指数退避，限制尝试次数与总时长，并控制应用并发。
只有在回退分组仍支持同一模型和协议时才应使用回退。创建更多 Key 不一定能绕过账号级或分组级限制。
499：从调用方往外排查
Modelflare 在下游连接完成前结束时可记录 499。检查调用方是否触发 Abort，客户端、负载均衡、CDN 或反向代理是否达到空闲或总超时，用户是否停止任务，以及流中是否只有工具事件而没有可见文本。
单独一条 499 不能证明模型或渠道宕机。需要结合首个有效输出时间、取消时间、相同模型与分组的邻近请求一起判断。流式专项步骤见 AI API 流式指南。
分层理解 5xx
- 500 可能是确定性的内部适配问题，原样重试仍会失败。
- 502 可能代表上游响应无效或不完整。
- 503 可能代表没有可用路由或暂时不可用。
- 504 说明某一层时间预算已耗尽，但仍需定位是哪一层。
保留原始状态和结构化错误，不要让客户端把所有失败统一改写成模糊的 500。
是否应该重试
| 失败类型 | 默认决策 |
|---|---|
| 请求或协议无效 | 修正请求，不原样重试 |
| Key 无效或访问被拒 | 修正凭据或策略，不原样重试 |
| 额度耗尽 | 有意调整额度，不循环请求 |
| 限流 | 在允许时进行有界退避 |
| 暂时性 502/503/504 | 仅对可安全重复的操作进行有限次重试 |
| 客户端取消 | 只有用户仍需要且不会产生重复副作用时才重试 |
| 工具或写入副作用 | 先提供应用级幂等能力 |
每次重试都是新的工作，也可能产生新的费用。记录每一次尝试，不要让后来的成功掩盖最初错误。
安全保留哪些证据
建议记录请求 ID、UTC 时间、端点、流式模式、请求模型、所选分组、HTTP 状态、结构化错误码、总耗时、首个有效输出时间以及调用方是否取消。描述请求是否使用工具或图片即可，不要在普通日志中附带完整 Key、Prompt、响应正文、原始请求体、邮箱或明文 IP。
定位失败层后，可继续参考可靠的 AI API 路由设计回退。
常见问题
403 能证明供应商宕机吗？
不能。账号、Key、模型、分组、IP 或能力策略都可能在选择上游前返回 403，应先看请求记录和精确错误码。
499 是标准的上游模型错误吗？
不是。在 Modelflare 请求记录中，它表示完成前观察到下游取消，应先检查调用方与代理的时间预算。
所有 5xx 都应该重试吗？
不应该。只重试可安全重复的操作，限制次数和总时间，并保存第一次错误。确定性的适配或请求问题不会因重复而改善。