流式响应首包超时与自动重试

流式请求偶尔会因上游排队或抖动长时间收不到首包。x-stream-header-* 系列请求头让网关在「等待首包超过设定秒数」时按你的策略处理：中止（abort）或自动重试（retry）。不添加对应请求头时，请求行为与原来完全一致。

ℹ

本页能力适用于经过网关发起的流式 HTTP 请求（如 POST /api/v1/chat/completions 且 stream: true）。非流式请求、异步任务接口、WebSocket 接口不使用本功能。

客户端请求

stream: true + x-stream-header-*

→

网关等待首包

每次尝试最多等 timeout 秒

→

✓ 首包到达

正常流式返回，计时器失效

✗ 超时

abort：直接返回 504
retry：预算内自动重试，耗尽后返回 504

快速开始

curl --no-buffer https://router.shengsuanyun.com/api/v1/chat/completions \
  -H "Authorization: Bearer ${SSY_API_KEY}" \
  -H 'Content-Type: application/json' \
  -H 'x-stream-header-timeout: 10' \
  -H 'x-stream-header-timeout-action: abort' \
  --data '{
    "model": "<MODEL>",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'

curl --no-buffer https://router.shengsuanyun.com/api/v1/chat/completions \
  -H "Authorization: Bearer ${SSY_API_KEY}" \
  -H 'Content-Type: application/json' \
  -H 'x-stream-header-timeout: 10' \
  -H 'x-stream-header-timeout-action: retry' \
  -H 'x-stream-header-max-retries: 1' \
  --data '{
    "model": "<MODEL>",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'

首个尝试等待 10 秒仍无首包时，由网关自动重新发起一次请求；第二次尝试仍超时则返回 504。

请求头说明

请求头	取值	缺省行为	说明
`x-stream-header-timeout`	≥ 0 的整数，单位秒	`0`	等待每次上游尝试返回首包的时间。`0` 表示不启用本功能。当前线上最大值为 `300`，超过后按 `300` 处理。
`x-stream-header-timeout-action`	`abort` / `retry`	`abort`	`abort` 表示超时后结束请求；`retry` 表示在预算内重新发起请求。未知值按 `abort` 处理。
`x-stream-header-max-retries`	≥ 0 的整数	`1`	允许的重试次数（不含第一次请求）；仅在 `action=retry` 时解析。当前线上最大值为 `2`，超过后按 `2` 处理。
`x-stream-header-retry-delay`	≥ 0 的整数，单位毫秒	`0`	每次自动重试前的等待时间。

线上默认值和上限可能随服务配置调整。建议只依赖「超过上限时会被限制」，不要依赖请求一定能采用高于上述数值的配置。

行为说明

首包超时不是整个请求的总超时

计时从网关建立上游会话并开始等待流式数据时启动，不包含此前的鉴权、请求解析和会话准备时间，也不限制首包到达后的完整内容生成时间。客户端观察到的总耗时通常会略大于设置的秒数——不要把它当作精确的端到端总耗时 SLA。

`max-retries` 表示额外尝试次数

x-stream-header-max-retries 不包含第一次请求：

有效的 max-retries	最多尝试次数	持续无首包时的大致等待时间（不含额外开销）
`0`	1	`timeout`
`1`	2	`2 × timeout + retry-delay`
`2`	3	`3 × timeout + 2 × retry-delay`

自动重试发生在网关内部：在重试成功并发出首包前，客户端不会收到前一次失败尝试的 SSE 内容。

重试可能增加耗时和用量

⚠

每次重试都会建立新的上游尝试，可能增加总体响应时间。若某次被中止的尝试已经产生了可计费的上游用量，系统仍会对这部分实际用量进行结算。建议从一次重试开始，根据业务对延迟、成功率和成本的要求谨慎调整。

超时响应

在 abort 模式下，或 retry 的预算耗尽后，网关返回 HTTP 504：

{
  "error": {
    "message": "upstream did not send the first response byte in time",
    "type": "server_error",
    "code": "stream_header_timeout"
  }
}

参数错误

以下情况返回 HTTP 400，error.code 为 invalid_request：

x-stream-header-timeout 不是整数或小于 0；
action=retry 时，x-stream-header-max-retries 不是整数或小于 0；
x-stream-header-retry-delay 不是整数或小于 0。

{
  "error": {
    "message": "invalid x-stream-header-timeout: \"abc\"",
    "type": "bad_request",
    "code": "invalid_request"
  }
}

ℹ

x-stream-header-max-retries 只在 action=retry 时生效和校验：abort 模式下该请求头会被忽略，即使它不是合法整数也不会因此返回 400。超过服务端上限的合法整数会被自动限制到上限，不会返回 400。

流式响应首包超时与自动重试

快速开始

请求头说明

行为说明

首包超时不是整个请求的总超时

max-retries 表示额外尝试次数

重试可能增加耗时和用量

超时响应

参数错误

推荐配置

`max-retries` 表示额外尝试次数