Idempotency and retries
Retry with the same Idempotency-Key to get exactly one task and one charge.
On this page
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.
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.