What is Idempotency
An operation is idempotent if performing it multiple times has the same effect as performing it once. In distributed systems, where network failures, timeouts, and retries are routine, idempotency ensures that repeating a request does not cause unintended side effects like duplicate charges, double-counted votes, or extra inventory deductions.
How it works
Some operations are naturally idempotent. Setting a value (SET balance = 100) produces the same result no matter how many times it runs. Deleting a resource by ID is idempotent -- deleting an already-deleted resource is a no-op. HTTP PUT and DELETE are specified as idempotent by the HTTP standard.
Other operations are not naturally idempotent. Incrementing a counter (INCREMENT balance BY 10) produces a different result each time. HTTP POST is not idempotent -- submitting the same order form twice creates two orders.
To make non-idempotent operations safe, systems use idempotency keys. The client generates a unique key (typically a UUID) for each logical request and includes it in every retry. The server stores the key along with the result. On subsequent requests with the same key, the server returns the stored result instead of re-executing the operation. Stripe, PayPal, and most payment APIs require idempotency keys for exactly this reason.
The server-side implementation requires durable storage of idempotency keys. A common pattern is to store the key in the same database transaction as the business operation, ensuring atomicity. If the transaction commits, the key is recorded. If it fails, both the key and the operation are rolled back, and the retry will execute the full operation again.
Idempotency keys must have a retention window. Storing every key forever is impractical. Most systems expire keys after 24-48 hours, which is long enough to cover any reasonable retry window.
Why it matters
In a distributed system, you cannot distinguish between a request that failed, a request that succeeded but whose response was lost, and a request that is still in flight. Without idempotency, retrying any of these cases risks duplicating the operation. Idempotency is not an optimization -- it is a correctness requirement for any system that operates over an unreliable network.
See How Distributed Transactions Work for the full walkthrough of sagas, idempotency, and compensation.