> ## 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.

# 排障手册

> 无图、慢、失败、扣费异常和模型不可用

排障时先定位问题在哪一层：鉴权、参数、模型、网络、余额、限流、上游服务或图片存储。

## 先收集这些信息

不要先猜原因。每个问题先收集一份固定排障包：

```text theme={null}
请求时间和时区：
接口路径：
模型：
接口类型：文本 / 图片 / 视频任务 / 支付
request_id：
upstream_request_id：
业务 task_id：
HTTP 状态码：
error.type：
error.code：
error.message：
任务错误 code/message：
请求参数摘要：
返回字段摘要：
是否已经转存到自有存储：
控制台用量截图：
```

`request_id` 可以从响应头 `X-Oneapi-Request-Id`、错误信息或控制台用量日志里找到。
如果控制台日志里有 `upstream_request_id`，也一起保留；它用于定位上游侧的问题。
任务和视频接口的失败不一定是 OpenAI 风格的 `{ "error": ... }`，也可能直接返回顶层 `code`、`message` 和 `data`。

按场景再补充这些字段：

| 场景   | 额外字段                                                            |
| ---- | --------------------------------------------------------------- |
| 文本接口 | `stream`、最后收到的片段、是否有 `usage`、前端是否过滤了空 `delta`                   |
| 图片接口 | `response_format`、`data.length`、返回的是 `url` 还是 `b64_json`、业务保存状态 |
| 视频任务 | `task_id`、`status`、`progress`、`fail_reason`、视频 URL 是否已转存        |
| 支付充值 | `trade_no`、`payment_provider`、订单 `status`、支付平台截图                |

## 快速定位表

| 现象               | 先看                                                                 |
| ---------------- | ------------------------------------------------------------------ |
| 400 / 413 / 422  | 请求字段、请求体大小、prompt 或输入图片                                            |
| 401              | API Key、请求头                                                        |
| 403              | 账户状态、模型权限、余额和 `error.code`                                         |
| 429              | [限流与并发](/production/rate-limits)                                   |
| 临时 5xx / timeout | [错误码与重试](/errors) 和 [超时处理](/production/timeouts)                   |
| 文本无输出或流式中断       | `stream` 设置、最后收到的片段、超时策略、用量日志                                      |
| 没有返回图片           | 参数、模型状态、输出格式                                                       |
| 视频任务没有结果         | `task_id`、任务状态、任务轮询和 [视频任务与结果](/video-generation/tasks-and-output) |
| 觉得被扣错费           | [失败不扣规则](/production/failure-refund)                               |
| 支付成功但余额未增加       | [计费与退款](/billing) 和充值订单状态                                          |
| 图片 URL 打不开       | [输出图片保存](/image-generation/output-images)                          |
| 视频 URL 打不开       | 任务是否成功、结果 URL 是否过期、是否已转存到自有存储                                      |
| 只返回 `b64_json`   | 解码后转存，确认代码没有只读取 `url`                                              |
| 返回 `data=[]`     | 按生成失败排查，记录模型、时间和业务 task\_id                                        |

## 决策流程

先分清错误结构：

```text theme={null}
普通 API 错误: 看 HTTP 状态码 + error.type + error.code + error.message
任务/视频错误: 看 HTTP 状态码 + 顶层 code + message + data
图片代理错误: 看 error.type 是否为 image_proxy_error
```

`error.code` 可能为空、缺失或由上游透传，不要只依赖单个字段做排障和重试。

```text theme={null}
先看 HTTP 状态码
  -> 4xx: 多数是请求、鉴权、余额或权限问题，不要自动重试
  -> 429: 降并发，指数退避，限制重试次数
  -> 5xx/timeout: 查 request_id、用量日志和结果保存状态
  -> 200 但业务失败: 查返回字段、data.length、保存链路
```

图片问题再加一层判断：

```text theme={null}
HTTP 200
  -> data 有图片: 转存失败就重试转存
  -> data=[]: 当作没有有效图片，保留 request_id 排障
  -> 只有 b64_json: 解码并转存
  -> URL 打不开: 尽快后端下载和转存，失败再查 error.type 是否为 image_proxy_error
```

## 常见判断

| 问题          | 判断方式                                                           | 下一步                             |
| ----------- | -------------------------------------------------------------- | ------------------------------- |
| 余额不足        | HTTP 常见为 403，`error.code` 常见为 `insufficient_user_quota`        | 充值或切换账户，不要自动重试                  |
| 预扣失败        | HTTP 常见为 403，`error.code` 常见为 `pre_consume_token_quota_failed` | 检查余额、订阅、令牌额度和 Key 配置            |
| 模型不可用       | `model_not_found` 或权限类提示                                       | 检查模型名、分组和控制台可用模型                |
| 参数错误        | 400 且 `error.message` 指向字段                                     | 修请求，不要重试                        |
| 内容被拒        | 422 或内容策略提示                                                    | 改 prompt、图片或模型                  |
| 限流          | 429 或负载饱和提示                                                    | 降并发，指数退避                        |
| 上游异常        | 5xx、`bad_response_status_code`                                 | 有限重试，仍失败就记录排障                   |
| 空图片         | HTTP 200 但 `data=[]`                                           | 视为没有有效图片，保留请求记录                 |
| 图片 URL 下载失败 | `error.type` 为 `image_proxy_error` 或上游 URL 下载失败                | 尽快重试下载并转存，仍失败联系支持               |
| 视频任务失败      | 任务 `status` 为失败，或顶层 `code/message` 提示失败                        | 保留 `task_id`、状态、错误信息和模型名        |
| 支付未到账       | 订单仍是 `pending`、`failed` 或 `expired`                            | 带 `trade_no`、支付网关、订单状态和支付截图联系支持 |

## 常见场景

### 文本接口无输出或流式中断

先确认请求是否真正成功：

1. 看 HTTP 状态码和 `request_id`
2. 如果是流式，记录最后一个收到的事件片段
3. 区分空 `delta`、保活事件和真正的模型内容
4. 看用量日志里是否有消费记录和 `upstream_request_id`
5. 如果前端无显示，确认前端没有把有效内容过滤掉

如果服务端已经有完整响应，但前端没展示，这是客户端解析或渲染问题，不应重复请求。

### 图片生成成功但用户看不到

先确认 Tapapi 是否已经返回图片：

1. 看 HTTP 是否 200
2. 看 `data.length`
3. 看返回的是 `url` 还是 `b64_json`
4. 看你的后端是否已经转存成功
5. 看前端是否读取了正确字段

如果模型已返回有效图片，但你的存储失败，这是保存链路问题，不应重复生成。

### 视频任务一直没有结果

先不要重复提交同一个生成请求，先查任务：

1. 看提交接口是否返回 `task_id`
2. 查询任务状态、进度和失败原因
3. 如果状态还在排队或生成中，继续按轮询策略等待
4. 如果状态失败，记录顶层 `code/message/data`
5. 如果状态成功但 URL 打不开，先检查是否已经转存和 URL 是否过期

视频结果链接更适合尽快转存到自有存储，避免后续因为上游链接过期而误判为生成失败。

### 批量任务突然大量失败

先停放量，然后看：

* 是否连续 429
* 是否同一模型大量 5xx 或 timeout
* 是否参数变化导致 400 / 422 增多
* 是否余额不足或触发预扣失败
* 是否对象存储上传失败

### 觉得扣费不对

按这个顺序对账：

1. 找到 `request_id`
2. 查控制台用量日志的最终 `quota`
3. 图片业务再对比你自己业务表里的 `requested_n`、`returned_count`、`saved_count`
4. 区分模型生成成功和业务转存失败
5. 视频任务再对比任务 `status`、`quota` 和最终结果
6. 带截图和脱敏请求摘要联系支持

<Warning>不要把 API Key、完整用户隐私数据、未脱敏图片链接直接贴到公开渠道。支持排障只需要脱敏后的请求体、模型名、时间和错误信息。</Warning>