Idempotency

An operation is idempotent if running it twice has the same effect as running it once. Setting a value to 5 is idempotent: assign x = 5 a hundred times and x is still 5. Incrementing a counter is not idempotent: x = x + 1 run three times gives a different result than running it once.

In HTTP this is built into the method semantics. GET, PUT, and DELETE are defined as idempotent. GET reads and changes nothing. PUT replaces a resource with a full representation, so repeating it overwrites with the same data. DELETE removes a resource, and deleting an already-deleted resource leaves the same end state (gone). POST is the odd one out: it is not idempotent, because each POST is meant to create a new resource, so two POSTs create two records.

The word matters because networks are unreliable. A client sends a request, the server processes it, and the response gets lost on the way back. The client cannot tell whether the operation succeeded or failed, so it retries. If the operation is idempotent, the retry is harmless. If it is not, the retry can double-charge a card or place a second order.

Most real systems need to make a non-idempotent operation like a payment safe to retry. The standard technique is an idempotency key: a unique token the client generates (usually a UUID) and sends with the request, often in an HTTP header like Idempotency-Key.

On the first request, the server records the key together with the result of the operation in a store such as Redis or a Postgres table, then returns the response. If the same key arrives again, the server sees it has already processed that key and returns the saved response instead of executing the operation a second time. The charge happens exactly once even if the client retries ten times.

Two details make or break this. First, the lookup and the write must be atomic, usually a database row with a unique constraint on the key, so two concurrent retries cannot both slip through. Second, keys need a time-to-live. Stripe keeps idempotency keys for 24 hours, after which the same key can be reused. The client must generate a fresh key per logical operation, not per retry, so all retries of the same intent share one key.

Use idempotency wherever a retry could cause damage: payment APIs, order placement, sending email or SMS, message consumers reading from a queue, and any write endpoint behind a load balancer or proxy that might re-send on timeout. Message systems like Kafka and SQS deliver at least once, meaning duplicates are expected, so consumers must be idempotent to be correct.

The cost is real but small. You need somewhere to store keys and their results, you pay an extra lookup on every write, and you have to decide on a TTL and a key-generation scheme. Storing the full response so retries get an identical answer adds more storage than just storing a boolean.

The common mistake is assuming a database unique constraint alone gives you idempotency. It prevents duplicate rows, but the client still gets an error on the retry instead of the original success response, which often triggers more retries. True idempotency returns the same successful answer to the duplicate request, not an error.

Stripe is the textbook case. When you create a charge, you pass an Idempotency-Key header with a UUID you generate. If your server times out waiting for Stripe and you retry with the same key, Stripe recognizes it and returns the original charge object rather than charging the customer twice.

Picture an e-commerce checkout. The shopper clicks Pay, the browser sends the request, but the mobile connection drops before the confirmation arrives. The app retries automatically. Without an idempotency key, the customer is charged twice and you get a chargeback and a support ticket. With the key generated once at checkout and reused across retries, the second request is a no-op that returns the same success.

The same pattern shows up everywhere money or side effects are involved. PayPal, Adyen, and most modern payment processors expose idempotency keys, and internal microservices copy the design for their own write endpoints.