报错速查表：401、404、429、5xx 分别意味着什么

同一条报错，在不同环节含义完全不同：429 可能是你的并发太高，也可能是上游在限流，还可能是整台网关挤满了。判断「这口锅归谁」，比记住错误码本身更有用。

先看状态码：谁的问题

429 的三种来源，别急着加钱

• 账户级限流：你自己的 RPM / TPM 配额打满了——降低并发或换更小的模型；
• 上游限流：站点把官方账号池的配额吃满了——与你无关，重试或换时段；
• 共享池拥挤：整台网关都在排队——表现为失败率与 p90 延迟同时上升，等低谷时段再跑。

400 里最常遇到的两个：上下文超长与 max_tokens

上下文超长的报错通常是 context length exceeded / too many tokens，注意它是「输入 + 输出」一起算的：你留的 max_tokens 也算在窗口里。长文档场景建议先本地估算 token 数，或改用检索只带相关片段。

5xx 与「网关无法连接上游」

这类报错几乎都不是你代码的问题。中转站的架构是「你的请求 → 网关 → 上游」，网关连不上上游时会给 502；上游思考太久没返回，会被判成 120 秒超时就断开，前端看到的就是 502 或连接被重置。

• 偶发一次：直接重试，别改代码；
• 固定某个模型必失败：该分组的上游挂了，换模型或换站；
• 高峰期大面积失败：容量问题，属于站点选型时要考虑的风险；
• 长输出任务必失败：把单次输出拆小，或改用流式输出。

返回「成功」但结果是坏的

推荐的排查顺序

1. ① 单发一条最小请求用 curl 和一个只有两个字回答的提示，排除并发与长上下文因素。
2. ② 换 Key / 换模型 / 换站各试一次三个变量只动一个，就能定位是账户、模型还是站点的问题。
3. ③ 打开日志记录 request-id多数网关会回传 request id 或 trace id，拿它去问客服比描述现象有效得多。
4. ④ 记录时间与频率「每天 22 点必慢」这类规律是共享池拥挤的典型证据，也是换站时的判断依据。