故障排查：你真正会遇到的错误
四种失败模式覆盖了几乎所有情况：鉴权、积分、限流与上游故障。下面说明每种含义与处理方式。
统一的错误结构
所有路由返回同一种结构：{ "error": { "message", "type", "code", "param" } }。用 code 分支（稳定），把 message 记日志（给人看），忽略 param（始终为 null）。
状态码速查
401 鉴权失败 · 402 积分不足 · 413 负载过大 · 425 相同的幂等请求仍在准备 · 429 触发速率或并发上限 · 499 调用方提前断开 · 500 我方缺陷 · 502 上游失败 · 503 暂无可用供应商 · 504 上游超时。
每个 key 两条限流
每分钟 60 次请求，外加未完成任务数上限。两者都按 key 计；并发提交任务时，通常先撞到的是未完成任务上限。
逐步做法
1. 401 invalid_api_key
key 缺失、格式错误或已撤销。用 bearer token 发送，不要放进 query string。
2. 402 积分不足
同一形状重试没有意义——它需要积分，不需要退避。重试前先看余额。
3. 429 速率或并发
退避后重试。把工作合并成更少、更长的任务，而不是大量短任务并行。
4. 503 no_available_provider
指数退避后重试。这是我方短暂无法服务，不是请求写错了——不要改写负载。
5. 504 上游超时
供应商没有及时响应。重试一次；如果反复出现，把该步骤换到另一个模型或供应商。
中文内容导航
继续阅读
常见问题
错误码与 OpenAI 兼容吗？
type 字段沿用 OpenAI 的分类，方便已有客户端继续用 switch；code 是我们更具体、更稳定的值。
什么情况下会收到 425？
在第一个相同的幂等请求仍在准备时又发了一次。稍等片刻，并复用同一个幂等键。
完整细节在哪里？
「错误与限额」参考列出了所有状态码、两条限流，以及失败时积分如何处理。