返回博客

流式响应里的故障切换边界

网关什么时候会重试、什么时候绝不重试,以及为什么流式输出开始后不能回放。

故障切换听起来像是“失败了自动换一个”。这句话对了一半——关键是分界线在哪里。

会重试的:传输层和上游的临时错误

网关会在这些情况下换一把 Key 或换一家上游:

  • 401 / 403
  • 429
  • 5xx
  • 连接层面的错误

这些都意味着“这个 Key / 这家上游现在不行,换一个可能行”。

不会重试的:你的请求本身有问题

400 会原样返回给你。网关不会把它转发给下一家上游。

原因是明确的:同样的请求换一个上游,大概率还是 400。重试它只会把一次失败变成多次失败,顺便多花一份配额。

有一个看起来像 400 的例外值得单独说:

OpenRouter 和 OpenCode Zen 要求模型进行推理。如果你发送了关闭推理的参数——reasoning_effort: "none"、reasoning: { enabled: false }、thinking: { type: "disabled" } 或 enable_thinking: false——网关会返回一个 400,提示你把等级改成 low、medium、high、xhigh 或 max。

但这里的关键在于:这个决定发生在挑选上游的时候,而不是重试的时候。 不兼容的上游根本不会收到请求。所以用 space-bunny 自动路由时,这个请求会直接落到 Command Code,而不是先打到 OpenRouter 再失败一次。

流式响应开始之后,就不再重试了

这是最重要的一条边界。

网关对流式响应是纯透传:上游的 SSE 帧原样转发,不重新分块、不重新编码。工具调用、多模态参数、SSE 事件全部保持上游原样。

一旦响应头发出、第一个字节流向客户端,网关就不会重放这个请求。原因很实际:如果上游已经吐出了半段回复再失败,重放会得到一段从头开始的重复内容。半句话重复一次,比一次明确的失败更糟。

所以故障切换发生在响应开始之前。等你的客户端已经收到内容,就只剩失败这一种结果。

一个共享的时间预算

所有 Key 重试、上游切换,以及最后的响应体和 SSE 流,都共用一个总预算。默认 300 秒:

GATEWAY_REQUEST_TIMEOUT_SECS=300

范围是 1 到 86400 秒,改动后需要重启网关。

预算耗尽时的行为分两种:

  • 响应头还没发出 → 返回 504
  • 响应头已经发出 → 直接切断这个流

这也是“不重放”策略的另一面:预算不是一次重试的额度,而是整个请求的额度。

怎么知道是谁答的

每个响应都带一个 x-gateway-provider 头,写明真正应答的那家上游。调试路由问题时,先看这个头,再看 GET /api/status 里的 requests、fallbacks 和 key_retries 计数。

这些计数和冷却状态都在内存里,重启后清零。