Idempotency
Every POST, PATCH and DELETE requires the Idempotency-Key header: a value
that is unique per operation, for example a UUID generated by your system.
Idempotency-Key: 2f1d9a52-0b6c-4c3e-9d8e-7a1b2c3d4e5f- Repeating the same request with the same key within 24 h returns the same
response without running it again (header
Idempotent-Replayed: true). Use this to retry safely after a network error. - The same key with a different body responds
409 idempotency_conflict. - While the first request is still running, it responds
409 request_in_progress. - A transient refusal (
retryable: true, such as503) releases the key: the retry runs again. - If the outcome is uncertain (for example, the provider didn’t respond), the
response is
202with"status": "unknown"and retrying with the same key responds409 request_outcome_unknown. Nothing runs twice. Check the resource before trying again with a different key.
Best practice
Section titled “Best practice”Derive the key from what the operation means in your system (for example
order-1234-shipped): that way a retry from your own process never sends the
same message twice.