How do idempotency keys work for POST requests?

Summary

The client sends a unique Idempotency-Key header per logical operation; the server stores the key with a hash of the request and the resulting response, and if the same key arrives again it returns the stored response instead of performing the operation twice.

Longer Answer

Handle concurrent duplicates (lock or 'in progress' state returning 409), reject reuse of a key with a different payload, scope keys per client, and expire them after a retention window (e.g., 24h). Essential for payments and order creation.

Key Points

• Client-generated key per operation
• Store request hash + response
• Handle in-flight duplicates
• Expire keys