What is idempotency?
A property of an operation where running it multiple times produces the same result as running it once, critical for safe retries in distributed systems.
Also known as: idempotency
An operation is idempotent if calling it twice (or N times) leaves the system in the same state as calling it once. Setting a user's email to alice@example.com is idempotent; charging $10 to a credit card is not. The distinction matters because networks fail mid-request: if you do not know whether the server processed your call, you have to either retry (and risk duplication) or give up (and risk losing work).
HTTP bakes idempotency into its method semantics. GET, PUT, and DELETE are defined as idempotent; POST and PATCH typically are not. That is why retry-on-failure is safe with PUT but dangerous with POST, and why payment APIs (Stripe, Square, Adyen) all support an Idempotency-Key header: the server stores the result of the first call under that key and returns the cached result on every retry.
Building idempotent endpoints often comes down to one question: what is the natural unique key for this operation? An order create that takes a client_order_id is naturally idempotent. A payment that takes an idempotency_key is explicitly so. Without one, you are stuck deduplicating after the fact.
In the wild
- Stripe accepting an
Idempotency-Key: abc123header so a retried charge does not double-bill - A REST API returning the same response on a duplicate PUT because the resource state is unchanged
- A queue worker designed to be safely retried because every step writes a row with a deterministic primary key