速率限制与并发
了解每分钟请求数、并发任务数限制,以及如何正确退避重试。
两个独立限制
账户按请求用途分别限速,并单独限制生成并发。
| 限制 | 约束内容 | 默认值 | 拒绝时的响应头 |
|---|---|---|---|
| 提交类请求 | createTask、队列取消、申请上传签名和显式完成素材上传 | 100 次 / 分钟 | Retry-After |
| 任务轮询 | recordInfo | 120 次 / 分钟或并发上限 × 20,取较高值 | Retry-After |
| 账户读取 | 媒体报价、提交回执、临时上传确认和账户余额 | 120 次 / 分钟 | Retry-After |
| 并发任务数 | 同时运行中的生成任务数量 | 10 | Retry-After |
任一限制超限都会返回 HTTP 429。该请求不计费,也不会创建任务。
响应头
被限流时,响应会带上以秒为单位的 Retry-After,请至少等待该时长后再发起下一次请求。
HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json
{"code":"rate_limit","message":"Request rate limit reached"}媒体任务并发超限时,limit 是触发的并发上限,current 是该上限下计入的在途任务数。请等待现有任务结束,并按 Retry-After 退避。频率超限返回 rate_limit。
{"code":"concurrency_limit","message":"Concurrent task limit reached","limit":10,"current":10}轮询也占用配额
recordInfo 使用独立轮询配额。单个任务每秒轮询一次,每分钟会用 60 次配额。十个任务每秒轮询一次,每分钟会用 600 次。
推荐做法:
- 优先按
lifecycle.pollAfterSeconds等待。未返回该字段时,单个任务轮询间隔至少为 3 秒。 - 合并轮询:维护待查任务 ID 列表,一次遍历统一查询,而不是每个任务各起一个定时器。
- 生产环境优先使用,轮询作为兜底而非主要完成信号。
退避策略
使用带抖动的指数退避,并设置上限:
- 首次间隔 2–5 秒。
- 每次尝试乘以 1.5–2。
- 间隔上限 30–60 秒。
- 加入最多 20% 的随机抖动,避免多个 worker 同时重试。
- 达到最大尝试次数后停止,并把任务 ID 返回给用户。
重试 recordInfo 永远安全。重试 createTask 只有在复用同一 Idempotency-Key 且请求体完全一致时才安全,详见。
提升限额
并发数按客户单独配置。业务量需要更高档位时请联系支持;正常业务出现持续 429 通常就是需要提额的信号。

