Glossary · Software Architecture
What is Idempotency?
Short answer
Idempotency means an operation can be performed more than once with the same result as performing it once. An idempotent API request, such as “charge order 123” sent with the same idempotency key, won’t charge twice if the client retries after a timeout. It is essential wherever networks fail and messages or requests can be repeated.
Why it matters
When a request times out, the client cannot tell whether the server processed it. Retrying is the only safe option, so the server must make retries harmless. The same applies to queue consumers and webhooks, which most systems deliver “at least once”, meaning sometimes twice.
How to make operations idempotent
- Idempotency keys: the client sends a unique key (often a UUID) in a header such as
Idempotency-Key. The server stores the key with the result and, on a repeat, returns the stored result instead of acting again. Stripe’s API works this way. - Natural keys and upserts: “set the status of order 123 to shipped” is naturally idempotent; “add 1 to the stock” is not.
- Processed-message log: queue consumers record the IDs of handled messages and skip duplicates, ideally in the same database transaction as the work.
- Unique constraints: let the database reject a second insert of the same payment or event.
HTTP methods
By definition GET, PUT and DELETE are idempotent and POST is not, but that only holds if your implementation respects it. Treat it as a contract you must test.
