> ## Documentation Index
> Fetch the complete documentation index at: https://docs.focusapi.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 524 网关超时：长请求与流式排查

> FocusAPI 接口返回 HTTP 524 网关超时错误的完整排查与规避方案：缩短 prompt 长度、降低 max_tokens 上限、改用 SSE 流式输出降低首包延迟、调大客户端读超时、改用异步任务轮询接口，并对比与 429 限流错误的差异及典型触发场景。

## 现象

* HTTP 状态码 **524**（或网关返回的超时类错误）
* 客户端长时间等待后失败
* 流式请求中途断开

## 常见原因

1. **模型推理时间过长**（大模型、长上下文、推理模型）
2. **生成 token 过多**（`max_tokens` 过大）
3. 客户端 **读超时** 设置过短
4. 网络不稳定或跨境链路延迟高
5. 图像 / 音频 / 视频等 **重任务** 超过同步等待上限

## 处理步骤

<Steps>
  <Step title="缩短单次请求">
    减少 `max_tokens`、压缩 prompt、换用更快模型（如 flash / mini 系列）。
  </Step>

  <Step title="调大客户端超时">
    SDK / HTTP 客户端读超时建议 ≥ 120s（按业务调整），流式场景需持续读流。
  </Step>

  <Step title="改用流式">
    对话场景设置 `"stream": true`，尽早收到首包，降低「长时间无响应」感受。见 [文本对话](/models/chat#流式输出)。
  </Step>

  <Step title="异步任务类能力">
    若 API 返回 `task_id`，按厂商文档轮询任务状态，勿单次同步等待过久。
  </Step>

  <Step title="重试">
    超时偶发时可重试 1～2 次；持续失败请换模型或联系支持。
  </Step>
</Steps>

## 与 429 的区别

| 状态码 | 含义                 |
| --- | ------------------ |
| 429 | 请求 **太多**，需降速      |
| 524 | 单次请求 **太久**，需缩短或优化 |

## 相关文档

* [文本对话](/models/chat)
* [图像生成](/models/image-generation)
* [视频生成](/models/video-generation)