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

# 异步任务轮询429/5xx处理约定

> 轮询异步任务状态接口时，如何处理 429 限流与 5xx 临时故障。

本文档定义异步任务（视频、图片生成等）状态查询接口在 `429` 与 `5xx` 下的预期行为，供客户端实现轮询逻辑时参考。

## 适用范围

* `GET /v1/videos/:task_id`
* `GET /kling/v1/videos/:action/:task_id`
* `GET /kling/v1/images/:action/:task_id`
* `GET /vidu/ent/v2/tasks/:task_id/creations`
* `GET /minimax/v1/query/video_generation`
* `GET /minimax/v2/query/video_generation/:task_id`
* `GET /byteplus/api/v3/contents/generations/tasks/:id`

## 429 Too Many Requests

* 语义：临时性限流（请求频率、并发或分组负载），**不代表任务失败**。
* `Retry-After`：baze平台保证**所有** `429` 响应都携带 `Retry-After` 响应头，值为整数秒（默认 `5`）。如果下游处理已显式设置该头，则保留下游的值。
* 客户端预期处理：
  1. 读取 `Retry-After`，等待该秒数后再发起下一次查询。
  2. 不要将 `429` 视为任务终态，也不要计入"任务失败"次数。
  3. 若未读取到 `Retry-After`（例如经过不透明代理被剥离），按默认 `5` 秒退避。

## 5xx 内部错误 / 网关错误 / 服务不可用

* 语义：平台或上游渠道的临时故障。任务可能仍在上游正常执行，也可能已经失败，**不能从 `5xx` 直接推断任务终态**。
* 预期处理：**快速失败或有限重试**，不要无限重试。
  1. 建议采用指数退避（例如 `5s`、`10s`、`20s`…上限 `60s`）。
  2. 设置最大重试次数或总时长；超过阈值后中断本次轮询并向用户给出明确错误，保留 `task_id`，待服务恢复后可继续查询。
  3. 不要因为没有拿到 `status` 字段就当作"仍在排队"无限重试。
* 响应体约定：异步任务查询接口在 `5xx` 时仍会返回 JSON 响应体，并附带 `status` 标识与错误信息，用于区分"接口本身出错"与"任务正常排队"，例如：

```json theme={null}
{
  "code": "query_failed",
  "message": "query task failed",
  "data": null,
  "status": "running"
}
```

* `Retry-After`：异步任务查询接口在 `5xx` 时也会返回 `Retry-After`（默认 `5` 秒），但该头**仅对 `429` 做全局保证**，客户端不应依赖 `5xx` 一定带此头。

## 其他 4xx

除 `429` 外的 `4xx`（如 `task_not_exist`、参数错误、鉴权失败）属于确定性错误，应停止轮询并按错误信息处理。

## 保证矩阵

| 状态码 | 是否代表任务失败 | 响应体含 `status` | `Retry-After` | 客户端建议 |
| - | - | - | - | - |
| `200` | 否 | 是 | 否 | 按 `status` 判断是否继续轮询 |
| `429` | 否 | 视接口而定 | **保证存在** | 按 `Retry-After` 等待后重试 |
| `5xx`（异步查询接口） | 否 | 是（`running`） | 返回，但不做全局保证 | 有限重试、指数退避，超阈值中断 |
| 其他 `4xx` | 是（确定性错误） | 否 | 否 | 停止轮询并处理错误 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.