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

# 超时处理

> 客户端超时、服务端超时和长任务建议

模型请求可能因为模型耗时、排队、网络、参考文件下载、流式长时间无数据或结果文件回传失败而超时。超时处理要先区分“客户端等不住了”和“平台或上游已经失败”。

<Warning>前端 timeout 不等于模型请求一定失败。只要你的后端已经把请求发给 Tapapi，就必须结合 HTTP 响应、`request_id`、用量日志和结果保存状态判断，不能直接无限补跑。</Warning>

## 常见原因

| 类型      | 说明                               |
| ------- | -------------------------------- |
| 客户端超时   | SDK、代理、浏览器或你的网关等待时间太短            |
| 上游超时    | 模型处理、排队或文件回传超过上游能力               |
| 流式无数据超时 | 流式请求长时间没有新 token 或事件             |
| 图片代理超时  | 返回 URL 可以拿到，但代理下载上游图片失败或超过代理取图窗口 |
| 业务队列超时  | 你的 worker 排队太久，用户端已经放弃等待         |

## 推荐做法

| 层级        | 建议                                   |
| --------- | ------------------------------------ |
| 浏览器前端     | 不直接暴露 Tapapi Key；前端只轮询你的业务任务状态       |
| 你的后端      | 设置比前端更长的 timeout，并记录请求结果             |
| Worker 队列 | 每个任务有最大运行时间、最大重试次数和幂等键               |
| Tapapi 响应 | 读取 HTTP 状态和 `error.code`，不要只看“前端等超时” |
| 对账        | 超时后先查业务记录和控制台用量，再决定是否补跑              |

建议从这些默认值开始，再按模型耗时调优：

| 场景      | 客户端建议                   |
| ------- | ----------------------- |
| 普通文本非流式 | 60-120 秒                |
| 文本流式    | 允许长连接，但要处理长时间无数据        |
| 普通图片生成  | 120-180 秒               |
| 慢速高质量图片 | 使用业务队列，不让用户浏览器一直等       |
| 批量生成    | worker 控制单任务超时，前端轮询业务状态 |

<Note>这些是你的应用侧建议值，不是平台 SLA。真实上游耗时会随模型、尺寸、质量、并发和排队变化。</Note>

Tapapi 平台侧的 relay HTTP client 不一定强制设置统一总超时；你的后端仍应根据业务场景设置自己的等待时间、队列超时和补跑规则。

## 流式请求

文本流式请求可能长时间没有新 token，尤其是推理模型、长上下文、工具调用或上游排队。你的客户端需要同时处理三件事：

| 场景     | 建议                         |
| ------ | -------------------------- |
| 长时间无数据 | 给用户展示“仍在生成”，不要立即重复提交       |
| 连接中断   | 保存已收到内容、`request_id` 和错误原因 |
| 用户关闭页面 | 后端仍可能继续收到上游结果，应按服务端最终记录对账  |

流式接口的最终用量以服务端记录为准。客户端断开只代表用户不再等待，不一定代表模型没有完成。

部分推理模型可能收到 ping、空 `delta` 或 keep-alive 事件。这类事件只表示连接仍然存活，不应展示成正文内容，也不应触发重复提交。

## 图片接口建议

| 场景      | 建议                                    |
| ------- | ------------------------------------- |
| 单张文生图   | 后端同步等待，前端展示加载状态                       |
| 高质量慢模型  | 后端设置更长 timeout，并给前端返回业务任务状态           |
| 批量生成    | 业务队列 + worker 调 Tapapi，同一任务最多重试 1-2 次 |
| URL 下载慢 | 生成成功后由后端转存，前端只访问自有存储                  |

图片 URL 返回后建议尽快由你的后端转存到 COS、S3、R2 或 OSS。不要把上游临时 URL 当作长期存储；如果 `image_proxy_error` 或下载超时，先重试下载和转存，仍失败再带 `request_id` 联系支持。

当前图片代理和视频结果代理都有有限取回窗口。生成或任务完成后，应尽快由你的后端拉取并转存结果，不要依赖代理 URL 长期可用。

## 504 / 524 怎么处理

`504` 和 `524` 通常代表长时间没有拿到最终结果。后端默认会把这类状态视为不适合盲目自动重试的错误，因为重复提交可能造成重复生成、重复排队或对账复杂。

这里说的是客户业务侧补跑策略，不等同于 Tapapi 平台内部的通道重试策略。你的业务代码应先确认没有有效结果，再决定是否补跑。

建议流程：

1. 保存业务 `task_id`、请求时间、模型、参数和错误响应
2. 保存响应头里的 `X-Oneapi-Request-Id`
3. 查询你的业务任务状态、控制台用量和结果存储
4. 如果确认没有成功结果，再由 worker 做最多 1 次补跑
5. 对慢模型降低并发或改成离线队列
6. 仍频繁发生时联系支持确认上游容量

## connection reset / 网络中断

网络中断可以有限重试，但必须有业务幂等设计。图片生成不是幂等计算，同一个 prompt 重跑可能得到不同结果，也可能让账单和用户体验变复杂。

批量任务推荐把状态拆清楚：

```text theme={null}
queued -> running -> succeeded
                 -> retrying
                 -> failed
```

只有确认没有有效结果时，才进入 `retrying`。

托管异步任务有平台任务超时清理，超时后会进入失败和返还流程；但普通图片同步主路径仍建议由你的业务系统维护队列状态、超时状态和补跑次数。