# 幂等与重试

用同一个 Idempotency-Key 重试，不会重复创建任务，也不会重复扣费。

网络会超时，响应会丢失。幂等键让你在「不知道上一次成没成功」时可以放心重发。

## 哪些请求要带

创建视频任务、取消视频任务和登记素材这三个操作必须带请求头 `Idempotency-Key`。

## 怎么生成

- 每个新操作生成一个新值，例如 UUID，在发送前保存下来。
- 长度 8–128 个字符，以字母或数字开头，只用字母、数字和 `.`、`_`、`:`、`-`。
- 唯一性按团队、操作和键确定，不按 API 密钥区分：同一团队的两把 API 密钥用同一个键也会被当成同一个操作。

## 结果不明时

请求超时、连接断开或收到 `500`、`503` 时，用原请求体和同一个已保存的键重发。已经成功的操作会返回原响应，不会再创建一次，也不会再扣一次费。重试时绝不生成新值。

```bash
IDEMPOTENCY_KEY=${IDEMPOTENCY_KEY:-$(uuidgen)}
```

示例代码都这样处理：环境变量里已有 `IDEMPOTENCY_KEY` 就复用，没有才生成一次，并提示你保存。

## 冲突

| 状态码 | error.code | 含义 |
| --- | --- | --- |
| 409 | `idempotency_conflict` | 同一个键已经用于另一个请求。重试原请求，或给新请求换一个新键。 |
| 409 | `idempotency_replay_expired` | 原操作的重放响应已过期，原操作不会再执行一次。按 ID 查询原对象。 |

## 取消的幂等

取消操作永久保留它的原响应。对同一个任务用新的键再次取消，会引用同一个取消操作，并返回当时冻结的任务状态。

## 下一步

- [处理错误](./api-docs-zh-errors.md)：错误响应的格式，以及哪些错误可以原样重试。
- [限流与额度](./api-docs-zh-limits.md)：请求频率、大请求并发、余额和素材额度都可能让新请求被拒绝。