Idempotency Keys

Idempotency keys allow clients to safely retry mutating API requests (POST, PATCH) without risk of duplicate side effects. The client generates a unique key (typically a UUID v4) and sends it in a request header (e.g., Idempotency-Key). The server stores the key alongside the response; if the same key is sent again, the server returns the stored response instead of re-executing the operation. This is critical for payment APIs, order creation, and any operation where duplication would cause real-world harm.

The server-side implementation stores the idempotency key, request fingerprint (method + path + body hash), and complete response (status code, headers, body) in a database or cache with a TTL (typically 24-48 hours). On subsequent requests with the same key, the server must verify that the request fingerprint matches -- if the same key is used with different parameters, it should return a 422 error to prevent misuse. The storage lookup and response creation must be atomic to handle concurrent retries correctly.

Idempotency keys interact with database transactions: the key should be recorded within the same transaction as the business operation to ensure consistency. If the transaction fails, the idempotency key should not be stored, allowing a genuine retry. The Stripe API is the canonical reference implementation for this pattern, and their approach of locking on the idempotency key during processing handles race conditions from concurrent requests with the same key.