异步任务轮询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 标识与错误信息，用于区分”接口本身出错”与”任务正常排队”，例如：

{
  "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	是（确定性错误）	否	否	停止轮询并处理错误