Idempotency keys
Send an Idempotency-Key with every POST, so a retry never does the work twice.
Ready before the writes. v1 is read-only, so no endpoint takes a POST yet. The rules below already apply, so you can build retries now. Writes are coming.
How it works#
Idempotency-Key: 5f0c8a62-3a8e-4d1b-9a35-6a1d2b7c9e40- Make a fresh key for each operation: a random UUID is ideal. Up to 255 characters.
- Send the same key again only to retry that same request.
- Keys are kept for 24 hours, per credential.
- The header is optional. Without it, a retried
POSTruns twice.
What you get back#
| You send | You get |
|---|---|
| A new key | The request runs. Its response is stored. |
| The same key, the same request | The stored response again, same status and body, with Idempotent-Replayed: true. Nothing runs twice. |
| The same key, a different request | 409 idempotency_key_reused. Different method, path, query or body all count. |
| The same key while the first is still running | 409 idempotency_key_in_progress, with Retry-After |
| A blank or over-long key | 400 idempotency_key_invalid |
A 5xx or 429 response is never stored. Retrying with the same key after one of those runs the request for real, which is what you want.
A replay still counts against your rate limit.