Idempotency Keys
An idempotency key is a client-provided unique identifier for a request. The server uses it to detect and de-duplicate retries, returning the same result without executing the operation twice.
Idempotency key = the 'confirmation number' on your order. Accidentally hit 'Place Order' twice? The store sees the same confirmation number and says 'already got that one, chief.'
Required whenever operations have side effects (payments, order creation, emails) and clients may retry on timeout or network error. The server stores the idempotency key alongside the result. On receiving a request: check if key exists → if yes, return cached result; if no, execute and store result with key. The key has a TTL (typically 24–48 hours) after which it expires and a duplicate request would be treated as new. Stripe's API is the industry reference implementation for idempotency keys.
Storage of idempotency keys must be atomic with the operation result. If you execute the operation and then store the key, a crash between the two means the second request executes again. Use a transaction: store the key in a pending state, execute the operation, mark the key as complete with the result. If a second request arrives while the first is in-flight (key is in pending state), return 409 Conflict — the client should wait and retry. The key must be scoped to the authenticated user (key = userID + clientProvidedKey) to prevent cross-user replay attacks. For message consumers, idempotency is implemented by recording processed message IDs in a deduplication table checked before processing.
For a payment API, I require the client to send an idempotency key in every POST request. The API gateway stores the key in Redis with a 24-hour TTL. Before processing, it checks Redis: if the key exists and is complete, it returns the stored response; if it's in-flight, it returns 202 Accepted with a retry-after header. The key is stored atomically with the payment record in Postgres using a unique constraint on (user_id, idempotency_key).
Generating idempotency keys on the server side instead of the client. The point of idempotency keys is to allow the client to safely retry a request it is not sure was received. If the server generates the key, the client cannot retry with the same key.