Idempotency

POST requests require an Idempotency-Key header (8–128 characters: letters, digits, . _ : -).

• The first successful response is stored for that key and replayed for retries, with Idempotent-Replayed: true.
• Reusing a key with a different body returns 422 idempotency_key_reused.
• Failed requests (4xx/5xx) are not stored, so you can fix and retry with the same key.
• Concurrent retries with the same key are serialised.

Use one key per logical operation, e.g. order-1042-checkout-1.