What is Idempotency?

What idempotency means

Idempotency describes an operation you can repeat without changing the outcome beyond the first time you ran it. The everyday analogy is an elevator call button: pressing it once summons the car, and pressing it five more times changes nothing. Setting a value is idempotent — "set the temperature to 70" lands on 70 no matter how many times you say it. Incrementing is not — "add 5" gives a different answer every time you repeat it.

In software this property is precious because the world is unreliable. Requests get lost, time out, and get sent again. If the operation behind a request is idempotent, a duplicate delivery is harmless. If it is not, that duplicate can mean a second order, a double charge, or two copies of a record — exactly the kind of bug that erodes trust in a system.

Where the term came from

The word comes from mathematics, where an operation is idempotent if applying it twice gives the same result as applying it once — taking the absolute value of a number, for instance. The term was borrowed into computing as networked and distributed systems made "did that actually happen?" a constant, practical question.

It became part of everyday web vocabulary through HTTP, whose specification defines certain methods as idempotent by design. It moved to center stage as payment and infrastructure APIs popularized the idempotency key — a way for clients to retry a request that might have a side effect without risking that the side effect happens twice. Today it is a baseline expectation for any serious API that does something consequential.

How it works

By HTTP convention, GET, PUT, and DELETE are idempotent — fetching a resource, replacing it with a fixed value, or deleting it leaves the same end state no matter how many times you repeat the call. POST usually is not, because each call tends to create something new. That is the gap an idempotency key fills: the client generates a unique key, attaches it to the request, and the server remembers it. If a request with that same key arrives again, the server skips the work and returns the original result.

Behind the scenes, idempotency is often enforced at the data layer. A uniqueness constraint on an order's idempotency key lets the database reject a duplicate outright. A consumer reading from a message queue records which message identifiers it has already handled and ignores repeats. The common thread is making "process this" check first whether the effect has already occurred, so a retry becomes a safe no-op rather than a second action.

When it matters

Idempotency matters most where a duplicate has real consequences — money, inventory, notifications, or anything users see. Anywhere a client might retry, a load balancer might re-route, or a queue might redeliver, you have to assume an operation could run more than once. Payments are the classic example: a charge request that times out leaves the client unsure whether it succeeded, and only an idempotency key makes the obvious retry safe. The same logic applies to creating orders, sending one-time emails, and applying account credits. Designing for it up front is far cheaper than reconciling duplicate records after the fact.

At QUANT LAB

We treat idempotency as a default requirement, not a nice-to-have, anywhere an operation has a side effect. When we wire up Stripe payments, we pass an idempotency key on charge and subscription requests and enforce uniqueness in Postgres, so a client retry or a duplicated webhook delivery can never result in a customer being billed twice. Stripe's own webhooks can arrive more than once by design, and our handlers are built to expect exactly that.

The same discipline runs through our API development work more broadly. Background workers that pull from a queue record what they have already processed, create-endpoints accept idempotency keys, and our pipelines retry failed operations freely because the operations themselves are safe to repeat. That is what lets a system recover gracefully from the network glitches that are inevitable rather than turning each one into a data-integrity incident.