---
title: "超时与长请求"
description: "pirouter 最多等 provider 600 秒开始返回，provider 沉默满 90 秒时先返回 200 并每 20 秒保活一次，所以客户端超时要设到 600 秒以上，并检查响应体里的 error。"
canonical: "https://pirouter.ai/zh/docs/guides/timeouts"
last-updated: "2026-10-17"
lang: "zh"
source: "content/docs/zh/guides/timeouts.mdx"
---

# 超时与长请求

pirouter 最多等 provider 600 秒开始返回，provider 沉默满 90 秒时先返回 200 并每 20 秒保活一次，所以客户端超时要设到 600 秒以上，并检查响应体里的 error。

pirouter 最多等 provider 600 秒开始返回。provider 沉默满 90 秒时，网关先回 `200` 并定时保活，让连接不被中间设备断开。客户端的超时要设到 600 秒以上。

## 超时

无论是否流式，pirouter 最多等 provider 600 秒开始返回。非流式响应要等整个回复生成完才开始，所以对它来说，这 600 秒覆盖整个回复。流式响应收到第一个事件之后，总时长没有限制。

provider 沉默超过 90 秒时，按[长请求](https://pirouter.ai/zh/docs/guides/timeouts.md#长请求)处理：响应以状态码 `200` 开始，之后的超时以响应体或流里的错误返回，`error.code` 是 `upstream_timeout`，`error.type` 是 `gateway_timeout`。超时可以重试。

客户端的超时要大于 600 秒。如果客户端只计算两个字节之间的间隔，也要大于 90 秒，因为第一个字节最晚 90 秒才到。设短了，会放弃那些网关本来能返回的请求。

## 长请求

有些请求要过好几分钟 provider 才开始返回：高质量的图像，或者先长时间推理再输出长篇回复的模型。为了在这期间保持连接，provider 沉默满 90 秒后，pirouter 自己先开始返回：发出状态码 `200`，之后每 20 秒按响应的格式保活一次：

- **非流式**：`Content-Type: application/json`，每次发一个空格。JSON 允许值前面有空白，所以响应体到达后，SDK 和 JSON 解析器照常就能读出。
- **流式**：`Content-Type: text/event-stream`，每次发一行注释 `: keepalive`。SSE 客户端会忽略注释行。provider 开始返回后，它的事件照常转发。

Gemini 的 `streamGenerateContent` 请求请带上 `alt=sse`。不带时 pirouter 把它当作非流式请求，用空格而不是 `: keepalive` 注释保活。provider 在 90 秒内开始返回的请求不受影响。

> **注意：** 长请求失败时状态码也是 `200`，只看状态码会把失败当成成功。检查非流式响应体里有没有顶层 `error` 键，或者流里有没有 `error` 事件。

这类响应有三点不同：

- **失败时状态码也是 `200`。** 状态码在 provider 返回之前就已发出。之后的失败，非流式响应写成带顶层 `error` 键的响应体，流式响应写成一个 `error` 事件，data 是错误对象。错误可能是 provider 自己的，也可能是 pirouter 的，例如等满 600 秒仍未开始返回时的 `upstream_timeout`。
- **只带 `X-Pi-Trace-Id`。** 响应头在任何 provider 返回之前就已发出，所以没有 `X-Pi-Provider`、`X-Pi-Model` 和 `X-Pi-Upstream-*`。报障时带上 trace ID。
- **超过 90 秒后不再换 provider。** pirouter 只在响应开始之前换 provider 或[回退模型](https://pirouter.ai/zh/docs/guides/fallbacks.md)。

一个流式请求保活之后超时，看到的是这样：

```text
: keepalive

: keepalive

event: error
data: {"error":{"message":"The upstream did not start responding within the time limit.","type":"gateway_timeout","code":"upstream_timeout"}}
```

## 下一步

- [错误码](https://pirouter.ai/zh/docs/api/errors.md): 每个错误码的含义，以及哪些错误可以重试。
- [生成与编辑图像](https://pirouter.ai/zh/docs/guides/images.md): 高质量图像常常超过 90 秒，会走长请求。