Skip to content

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 as 503) releases the key: the retry runs again.
  • If the outcome is uncertain (for example, the provider didn’t respond), the response is 202 with "status": "unknown" and retrying with the same key responds 409 request_outcome_unknown. Nothing runs twice. Check the resource before trying again with a different key.

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.