Claude API 超时、流式输出中断，排查的第一步是分清"收到了状态码"还是"连接层就出了问题"。收到 429、529、504 这类状态码，说明网络是通的，问题在配额、服务端负载或请求方式；连接重置、一直无响应、流式输出 200 之后中途停住，才需要往链路和网络方向查。下面按这个顺序逐步排查。
第一步：先看状态码，别一上来就换网络
只要 API 返回了带 request_id 的 JSON 错误，就说明你的请求已经到达服务端。根据 Claude API 官方文档的 Errors 页，常见状态码含义如下：
| 状态码 | 错误类型 | 含义与处理方向 |
|---|---|---|
| 400 | invalid_request_error | 请求格式或内容有问题；到达自行设置的支出上限时也会返回 400 |
| 401 / 403 | authentication_error / permission_error | 密钥无效，或当前密钥无权访问所请求的资源 |
| 413 | request_too_large | 请求体超过上限，Messages API 为 32 MB |
| 429 | rate_limit_error | 组织触达速率限制，或触达所在档位的月度支出上限 |
| 500 | api_error | 服务端内部错误，建议指数退避重试，仍持续则带上 request id 联系支持 |
| 504 | timeout_error | 请求处理超时，长请求建议改用流式 |
| 529 | overloaded_error | API 暂时过载，通常出现在整体流量较高时 |
每个响应都带有 request-id 头，报错时务必先记下它，后面无论是自查还是联系支持都用得上。
429 是配额问题，不是"网络差"
按官方文档，限额是在组织层面设定的，并且按模型分别计算，指标包括每分钟请求数（RPM）、输入 token（ITPM）和输出 token（OTPM），采用令牌桶算法持续补充。也就是说，429 与你的出口 IP 无关，换出口、换线路并不会增加配额。
429 的处理思路：读响应里的 retry-after 头，按它给出的秒数再重试；检查并发和调用频率；使用提示缓存降低计入限额的输入 token（对大多数模型，缓存读取的 token 不计入 ITPM）；用量突然大幅上升时，也可能触发所谓"加速限制"，官方建议逐步提升流量、保持稳定的使用模式。
另外有一种容易误判的 429：触达所在档位月度支出上限时，同样返回 429，但不带 retry-after，重试会一直失败，需要查看错误详情里的 error_code，并到控制台处理额度。
529 与 504：服务端或请求方式的问题
529 表示整体负载较高，属于服务端暂时过载，做好指数退避重试、必要时降低并发即可，和你本地网络没有直接关系。504 是请求处理超时，官方建议长时间运行的请求使用流式 Messages API，而不是一次性等待完整响应。
第二步：流式（SSE）中途停住，怎么查
流式响应基于服务器发送事件（SSE），客户端要保持一条连接持续接收内容。这里有两种情况，处理方式不同。
情况一：200 之后，流里面出现错误事件
流式响应可能已经返回了 200，再在流里面发出错误事件。这时标准的 HTTP 错误处理不会触发，需要在代码里处理流中的 error 事件。排查方法：打印并保存流里收到的最后几个事件，看是否有 error 类型，以及有没有收到正常的结束事件。
情况二：连接被中间网络设备丢弃
官方文档提醒，部分网络会在空闲一段时间后丢弃连接，导致请求失败或超时而收不到 Anthropic 的任何响应。症状是流停住了，既没有错误事件也没有结束事件。可以这样判断：
- 记录每次中断时已输出的时长和内容量，看是否集中在固定时长；
- 换一个网络（如手机热点）重复同一请求，对照是否消失；
- 直接集成 API 时，设置 TCP socket keep-alive，官方文档指出这可以缓解部分网络的空闲超时。
官方 SDK 也做了一层保护：它会校验非流式请求不应超过 10 分钟的超时，并设置 TCP keep-alive 选项。如果不需要逐步处理事件，可以让 SDK 帮你消费流，最后拿到完整消息，下面是官方文档里的 Python 写法：
with client.messages.stream(
max_tokens=128000,
messages=[{"role": "user", "content": "..."}],
model="claude-sonnet-5",
) as stream:
message = stream.get_final_message()官方 SDK 默认会对连接错误、限流和 5xx 做指数退避重试，默认两次，并遵循 retry-after，次数可通过 max_retries 调整。如果你在业务层又叠了一层重试，要注意幂等，否则流中断后重试可能造成重复生成。
第三步：一次排查的完整顺序
- 记录
request-id、状态码和错误类型，区分是 HTTP 错误、流中错误还是连接层故障。 - 如果是 429，先看
retry-after和当前用量，再检查并发；确认不是月度支出上限。 - 如果是 529 或 5xx，做指数退避重试，必要时降低并发。
- 如果是长请求超时，改用流式，并检查客户端的超时设置是否小于任务实际耗时。
- 如果是流停住或连接重置，换网络对照，并开启 TCP 保活。
- 以上都排除后，再考虑出口链路本身的质量问题。
可以用 curl 快速看一眼响应头，确认 request-id、限流相关头是否正常返回：
curl -sS -D - -o /dev/null https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model": "claude-sonnet-5", "max_tokens": 16, "messages": [{"role": "user", "content": "ping"}]}'什么情况下，才值得动网络方案
当错误出现在连接层：连接重置、握手超时、请求发出后长时间无响应，并且换网络后会变化、不同时段表现不同，这时链路质量才是主要嫌疑。典型情况包括：晚高峰明显变差、在命令行或 IDE 里报错而浏览器正常、长任务跑到一半反复断线。
这类问题可以从两个方向处理：一是确保命令行和 IDE 的流量真正走了加速通道，用全局或 TUN 模式接管系统流量，见 系统代理与 TUN 模式的区别；二是选择有持续探测和自动切换能力的线路方案，TonBoVPN 的智能路由即按这个方向设计，具体行为以官网当前说明为准。Claude Code 与 Cursor 长任务的断线细节，可以看 Claude Code 与 Cursor Agent 断线排查。
需要强调：独享 IP 解决的是出口被他人共用带来的信誉和验证问题，它并不能改变你的组织级 API 配额，所以不要期待它消除 429。限流类问题，应从调用频率、并发、缓存和档位上调整。
常见问题
SSE 中断后，需要重新发起整个请求吗？
多数情况下是的。除非你的业务层自己实现了基于已输出内容的续写，否则需要重新请求完整内容。因此减少中断，比事后补救更划算。
怎么快速区分 429 和连接错误？
429 是服务端返回的 HTTP 响应，带有 JSON 错误体和 request_id，通常还有 retry-after；连接重置、握手超时则根本没有 HTTP 响应，发生在 TCP 或 TLS 层。
本地正常，上线后超时变多，是为什么？
线上并发更高，更容易触发 RPM、ITPM 限制；部署环境的网络出口也可能和本地不同。建议上线前按预期并发压测，并监控 429 与超时的比例。
必须使用流式吗？
不必须，但官方建议长时间请求使用流式或批处理接口，尤其是预计超过 10 分钟的请求。短请求可以继续使用非流式。
排查 Claude API 的稳定性，核心是先分层：状态码决定方向，配额问题调频率，服务端问题做重试，连接层问题再查链路。按这个顺序走，比一遇到超时就换工具更快找到根因。
