# Idempotency and retries

Retry with the same Idempotency-Key to get exactly one task and one charge.

Networks time out and responses get lost. An idempotency key lets you send again safely when you do not know whether the last attempt worked.

## Which requests need one

Creating a video task, cancelling a video task and registering an asset must carry an `Idempotency-Key` header.

## Make a key

- Generate a new value for every new operation, such as a UUID, and save it before you send.
- Use 8–128 characters, starting with a letter or digit, with only letters, digits and `.`, `_`, `:` or `-`.
- Keys are unique per team, operation and key, not per API key: two API keys of one team sending the same key name the same operation.

## When the outcome is unknown

When a request times out, the connection drops, or you get `500` or `503`, resend the same body with the same saved key. An operation that already succeeded returns its original response; nothing is created or charged twice. Never generate a new value for a retry.

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

All samples work like this: they reuse `IDEMPOTENCY_KEY` from the environment, or generate it once and ask you to save it.

## Conflicts

| Status | error.code | Meaning |
| --- | --- | --- |
| 409 | `idempotency_conflict` | The key was already used for a different request. Retry the original request, or use a new key for a new request. |
| 409 | `idempotency_replay_expired` | The saved replay of the original operation expired; the operation is not run again. Read the original object by its ID. |

## Cancellation keys

A cancellation keeps its original response forever. Cancelling the same task again with a new key refers to the same cancellation and returns the task status saved at that time.

## Next steps

- [Handle errors](./api-docs-en-errors.md): The shape of error responses, and which errors you can retry as they are.
- [Rate limits and allowances](./api-docs-en-limits.md): Request rate, large-request concurrency, balance and asset allowances can each refuse a new request.