流式响应里的故障切换边界
网关什么时候会重试、什么时候绝不重试,以及为什么流式输出开始后不能回放。
故障切换听起来像是“失败了自动换一个”。这句话对了一半——关键是分界线在哪里。
会重试的:传输层和上游的临时错误
网关会在这些情况下换一把 Key 或换一家上游:
401/4034295xx- 连接层面的错误
这些都意味着“这个 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 计数。
这些计数和冷却状态都在内存里,重启后清零。