401 / 429 / 流式中断怎么排查

错误码本身不说明问题归属；用三步把「你的问题」和「站的问题」分开，才不会白折腾。

可引用结论

排查中转站报错的第一步不是问站方，而是用同一枚 Key 直连官方端点做对照：官方也失败说明是 Key 或账户问题，官方正常而中转失败才说明问题在中转层。429 需区分限流与余额（看 retry-after 与响应体关键词），流式中断需区分首包前断开与中途断开——两者的归因完全不同。

引用请注明来源 https://zhongzhuancha.com/guides/stream-errors（抓取日期 2026-10-28）。

每个码后面写清楚：谁的问题、怎么验证

5 类

顺序不能反：先排除自己，再看网络，最后才怀疑站点

从外到内

01
同一 Key 直连官方
把 base_url 换成官方地址、Key 不变。官方也报错 → 问题在你；官方正常 → 问题在中转层。这一步能排除掉七成的误判。
02
换模型与换协议
同一个 Key 换另一款模型、换 OpenAI 兼容 / Anthropic 兼容两种协议各试一次。只在一个组合下失败，说明是该渠道或该协议映射的问题。
03
连发 20 次看分布
统计成功率与耗时。全失败 → 站点级故障；间歇失败 → 负载均衡下某个上游渠道有问题；集中在长请求 → 超时配置过短。

失败率 = 失败次数 ÷ 总请求次数；判读阈值：<5% 可容忍，5–20% 需报障，>20% 建议停止生产流量

看起来都是「断了」，归因完全不同

首包前后

连接建立但没有任何 chunk 返回。多为鉴权、参数或上游拒绝，本质是请求没被接受，按 4xx 的思路排查。

已收到部分内容后中断。多为中转层超时设置短于模型输出时间，或上游长连接被切断。这类问题只在长回答时出现，短请求测不出来。

区分方法：记录首个 chunk 的时间戳。首个 chunk 从未到达是第一种；首个 chunk 到达后断开是第二种。报障时把这个时间点一起给对方，比说「老是断」有效得多。

＋401 到底是我的 Key 错了，还是中转站的问题？

两者都可能。先用同一枚 Key 直接请求官方端点：官方返回 401 说明 Key 本身无效或已过期；官方正常而中转返回 401，说明是中转层的鉴权映射问题。这一层区分不清，后面所有排查都是猜。

＋429 是限流还是余额不足？

通常 429 是速率或并发限制，余额不足一般返回 402 或 403。但中转站常把上游的 429 原样透传，所以看到 429 时先看响应体：带 retry-after 头的多半是真限流；带「quota」「balance」字样的其实是余额问题。

＋流式中断算失败吗？

算，但要分清位置。首个 chunk 之前断开，说明连接未建立；中途断开，通常是上游长连接被切断或中转层超时设置过短。前者看网络与鉴权，后者看超时配置。

＋为什么同样的请求，有时成功有时 5xx？

多上游负载均衡下，不同请求可能落到不同渠道。某个渠道故障时会周期性出现 5xx。连续发 20 次统计失败分布，看失败是否集中在特定时段或特定模型，能判断是渠道问题还是全站问题。