Idempotency
Retry any create call safely: a repeat never renders or charges twice.
In short: add an
Idempotency-Key header that names the work, such as the file name. If the network drops and you send it again, you get the first answer back instead of a second render.Send an Idempotency-Key header with any create call: 1 to 255 visible characters that name the work. If the same key arrives again within 24 hours with the same request, you get the first answer back, byte for byte, with Idempotent-Replayed: true. A first answer that was an error replays too.
Idempotency-Key: facade-042| Case | Answer |
|---|---|
| The same request again | The stored answer, with Idempotent-Replayed: true. |
| The same key with a different request | 409 CONFLICT, reason: key_reused. Use a new key for new work. |
| The same key while the first is still running | 409 CONFLICT, reason: in_progress. Wait a moment and retry. |
A retry after a 5xx | It runs again under the first attempt’s identity, so anything that already started is answered, not started twice. |
- Keys are scoped to your account, so two accounts can use the same key without colliding.
- Use something that names the work, such as the source file or a row id, so a retried batch lines up with the first attempt.
- With no header, the same request from the same key within 10 minutes is still caught and not charged twice. To render the same brief again on purpose, send
countor a key of your own. - With
count, each variation gets its own key derived from yours, so a retry replays them all.