Idempotency definition

Idempotency is the property of an operation that produces the same result whether it runs once or many times, so a retried request cannot double-charge a card or create a duplicate record. It matters most where delivery is unreliable, which is why content systems apply it to webhooks and writes: in Sanity, a document mutation targets a document by its `_id`, so replaying the same mutation converges on the same document rather than creating a second one.

What does idempotency mean in simple terms?

In simple terms, idempotency means doing something twice has the same effect as doing it once. Pressing the button for a floor in an elevator is idempotent, pressing it five more times does not take you five floors higher. Adding an item to a shopping cart is not idempotent, because each press adds another item.

The word comes from mathematics, where a function is idempotent if applying it to its own output changes nothing further. Taking the absolute value of a number is the classic example: abs(abs(-5)) is still 5. Software borrowed the term to describe operations that are safe to repeat.

The practical consequence is not “it can help to,” but “it does.” Idempotent operations are safe to retry. If a client sends a request and never hears back, it cannot tell whether the request failed or whether only the response was lost. If the operation is idempotent, the client can send it again and not worry about which of those two things happened.

Why does idempotency matter in APIs and distributed systems?

Idempotency matters in APIs and distributed systems because networks drop messages, and a sender cannot be certain whether a request arrived. Most delivery mechanisms, including webhooks and message queues, therefore guarantee at-least-once delivery: they keep retrying until they get an acknowledgment, which means the receiver can see the same message more than once.

At-least-once delivery only works if the receiver is idempotent. Without it, a retried webhook can send a customer two order confirmation emails, a retried write can create two copies of the same record, and a retried payment instruction can charge twice. The retry logic is not the bug, the non-idempotent handler on the other end is.

This is why payment APIs make the property explicit. Stripe lets a client attach an `Idempotency-Key` header to a POST request; if the same key arrives again, Stripe returns the stored result of the first attempt instead of performing the charge a second time. The pattern generalizes beyond payments, and it is a standard way to make an otherwise unsafe operation repeatable.

Which HTTP methods are idempotent?

In the HTTP specification, GET, HEAD, PUT, DELETE, OPTIONS, and TRACE are defined as idempotent, while POST and PATCH are not. Idempotency here is a property of the intended effect on the server, not of the response the client receives.

PUT is idempotent because it replaces a resource with a given representation: sending the same PUT ten times leaves the resource in the state that the first one set. DELETE is idempotent for the same reason, even though the first call may return 204 and later calls return 404. The status code differs, but the server state after each call is identical, and that is what the specification measures.

POST is not idempotent because it is defined as creating something new or triggering processing each time it is called. PATCH is not idempotent in general, because a patch can describe a relative change ("increment the counter by one") rather than a target state. A PATCH that sets absolute values can be idempotent in practice, but the method makes no promise.

A related but separate term is safe. GET and HEAD are safe because they are not supposed to change state at all. Every safe method is idempotent; the reverse is not true, since DELETE changes state but is still repeatable.

How do you make an operation idempotent?

You make an operation idempotent by giving each logical request a stable identity and having the server recognize repeats of it. Four common techniques cover most cases.

First, use an idempotency key. The client generates a unique identifier (often a UUID) for the attempt, sends it with the request, and the server stores the key along with the outcome. A second request carrying the same key returns the stored outcome instead of executing again. Keys are usually retained for a bounded window, such as 24 hours, and then expired.

Second, let the client supply the identifier for anything it creates, so a create is not “create a new thing,” but “upsert against a known address.” If the client decides the document ID, a replay writes to the same document rather than minting a new one.

Third, express changes as target states instead of deltas. "Set status to published" is repeatable; "toggle status" is not.

Fourth, deduplicate on the receiving side. Webhook and queue consumers can record the message ID or a hash of the payload and skip anything they have already handled, which turns at-least-once delivery into effectively-once processing. Closely related is convergence: an operation that always drives the system toward a declared desired state, the model used by infrastructure tools like Terraform and Kubernetes, is idempotent by construction.

What is the difference between idempotency and exactly-once delivery?

Idempotency is a property of the operation, while exactly-once delivery is a property of the transport, and the two are often confused. Exactly-once delivery promises that a message reaches the consumer precisely one time. Idempotency makes no promise about how many times the message arrives; it only guarantees that extra arrivals do nothing harmful.

The distinction matters because true exactly-once delivery across an unreliable network is generally impractical to implement end to end. Sender and receiver cannot reach certainty about a message in a finite number of round trips, so systems settle for at-least-once delivery combined with idempotent handling. The industry shorthand for that combination is effectively-once processing: duplicates still arrive, but they have no observable effect.

In day-to-day engineering terms, that means the reliable path is not to chase a transport that never duplicates, but to assume duplicates will happen and design handlers, writes, and content mutations so that a second copy converges on the same state as the first.

Last updated: September 20, 2026