HRouter

API 503、超时、流式输出中断怎么排查

503、请求超时、流式输出（stream）输到一半停住，是三类相关但原因不同的问题。503 是服务端暂时没有可用通道；超时和中断多数发生在客户端与服务之间的网络上。先分清是哪一种，再对症处理。

先分类

现象 最可能的方向
立刻返回 503，错误类型 api_error 分组里的通道暂时不可用，稍后重试
返回 503 API_KEY_AUTH_OVERLOADED 鉴权服务暂时繁忙，稍后重试
等很久后客户端报超时 网络、代理或请求本身太大
流式输出输到一半停住或断开 网络中断、代理或长时间空闲被切断

503：暂时没有可用通道

返回 503 且错误类型是 api_error，意思是：分组里能处理这个模型的通道存在，但暂时都不可用，例如正在冷却、触发了临时限流，或者分组暂时没有可用通道。这类问题通常会自己恢复。

  1. 稍后重试，等几十秒到几分钟。
  2. 用指数退避：1 秒、2 秒、4 秒地重试，不要无间隔地连续重试，那样只会让问题更长。
  3. 换同系列的其他模型，见 编程场景怎么选模型。
  4. 到 服务状态 查看是否有已知故障和最近的可用性记录。
  5. 持续数十分钟仍然 503，记录时间、模型和错误信息，联系平台。

503 和 model_not_found（404）的区别：404 是配置问题，重试没有意义；503 是暂时的，重试可能成功，见 model_not_found。

请求超时

超时是客户端等不到响应而放弃。常见原因：

原因 处理
客户端超时时间太短 长任务、大上下文、推理强度高时模型本来就慢，调大超时（SDK 里通常有 timeout 参数）
上下文太长 缩短提示词，或开启自动压缩，见 Codex 安装与配置
本地代理或 VPN 不稳定 临时关闭代理直连测试，或换一个稳定的线路
网络本身不稳 换网络再试，用 curl -i 看能不能收到响应头

流式输出中断

流式输出会让连接保持很久，更容易被中途切断：

  • 网络波动：移动网络、公共 Wi-Fi 容易断。
  • 代理或公司网关切断长连接：一些代理对空闲连接有时间限制，可以换直连测试。
  • 客户端自己放弃：IDE 插件或脚本里设置了较短的读取超时。
  • 请求太大或生成太长：缩小一次请求的范围。

处理办法：

  1. 先用 curl 流式请求验证服务端是否正常：
curl -N https://hrouter.net/v1/chat/completions \
  -H "Authorization: Bearer $HROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\": \"$HROUTER_MODEL\", \"stream\": true, \"messages\": [{\"role\": \"user\", \"content\": \"数到二十\"}]}"
  1. curl 正常而客户端中断：问题在客户端或网络，检查代理、超时设置。
  2. curl 也会中断：记录发生的时间点，在 服务状态 对照，并联系平台。
  3. 在 Codex、Claude Code 里中断后，重新发送同一个任务通常可以继续。

排查清单

  1. 返回的是 503 还是客户端超时？
  2. 用 curl 直接请求 /v1/models，能不能立即返回 200？
  3. 换一个模型，同样的问题还在吗？
  4. 关闭代理 / VPN，直连试一次。
  5. 查看 服务状态。

相关阅读