# 速率限制与并发

## 两个独立限制

账户按请求用途分别限速，并单独限制生成并发。

| 限制 | 约束内容 | 默认值 | 拒绝时的响应头 |
| --- | --- | --- | --- |
| 提交类请求 | `createTask`、队列取消、申请上传签名和显式完成素材上传 | 100 次 / 分钟 | `Retry-After` |
| 任务轮询 | `recordInfo` | 120 次 / 分钟或并发上限 × 20，取较高值 | `Retry-After` |
| 账户读取 | 媒体报价、提交回执、临时上传确认和账户余额 | 120 次 / 分钟 | `Retry-After` |
| 并发任务数 | 同时运行中的生成任务数量 | 10 | `Retry-After` |

任一限制超限都会返回 HTTP `429`。该请求不计费，也不会创建任务。

## 响应头

被限流时，响应会带上以秒为单位的 `Retry-After`，请至少等待该时长后再发起下一次请求。

```http
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`。

```json
{"code":"concurrency_limit","message":"Concurrent task limit reached","limit":10,"current":10}
```

## 轮询也占用配额

`recordInfo` 使用独立轮询配额。单个任务每秒轮询一次，每分钟会用 60 次配额。十个任务每秒轮询一次，每分钟会用 600 次。

推荐做法：

- 优先按 `lifecycle.pollAfterSeconds` 等待。未返回该字段时，单个任务轮询间隔至少为 3 秒。
- 合并轮询：维护待查任务 ID 列表，一次遍历统一查询，而不是每个任务各起一个定时器。
- 生产环境优先使用[任务回调](/docs/webhooks)，轮询作为兜底而非主要完成信号。

## 退避策略

使用带抖动的指数退避，并设置上限：

1. 首次间隔 2–5 秒。
2. 每次尝试乘以 1.5–2。
3. 间隔上限 30–60 秒。
4. 加入最多 20% 的随机抖动，避免多个 worker 同时重试。
5. 达到最大尝试次数后停止，并把任务 ID 返回给用户。

重试 `recordInfo` 永远安全。重试 `createTask` 只有在复用同一 `Idempotency-Key` 且请求体完全一致时才安全，详见[错误与重试](/docs/errors)。

## 提升限额

并发数按客户单独配置。业务量需要更高档位时请联系支持；正常业务出现持续 `429` 通常就是需要提额的信号。