Idempotency is a property of operations where performing the same action multiple times produces the same result as performing it once. It is a foundational concept in API design, distributed systems, and database engineering that enables safe retries and predictable behavior.
An operation is idempotent if applying it one time or many times yields the same outcome and system state. The term originates from mathematics, where f(f(x)) = f(x) for an idempotent function. In software, this means a duplicate request — caused by a network retry, timeout, or client bug — does not cause unintended side effects like duplicate charges or double-inserted records.
In distributed systems, networks are unreliable: requests can time out, be dropped, or be delivered more than once. Without idempotency, a client that retries a failed payment request could charge a customer twice. Idempotent APIs allow clients to safely retry operations without coordinating complex rollback logic, dramatically simplifying error handling and improving resilience.
The HTTP specification defines GET, PUT, DELETE, HEAD, and OPTIONS as idempotent methods because repeating them does not change the server state beyond the first call. POST is explicitly non-idempotent because each call typically creates a new resource or triggers a new action. PATCH is situationally idempotent depending on how the update is expressed — setting a value absolutely is idempotent, but incrementing it is not.
A common pattern for making non-idempotent endpoints safe is the idempotency key — a unique client-generated token (usually a UUID) sent in a request header such as Idempotency-Key. The server stores the key alongside the result of the first successful execution; subsequent requests with the same key return the cached result instead of re-executing the operation. Stripe, PayPal, and most modern payment APIs use this pattern to guarantee that retried payment requests never double-charge customers.
SQL's INSERT ... ON CONFLICT DO NOTHING (upsert) and MERGE statements are idempotent alternatives to plain INSERT, preventing duplicate-key errors on retries. Database operations like DELETE WHERE id = 42 are naturally idempotent: once the row is gone, subsequent calls simply find nothing to delete and return success. Designing database mutations to be idempotent by default reduces the need for complex deduplication logic at the application layer.
Idempotency is often confused with safety — a safe operation has no side effects (like a GET), while an idempotent operation may have side effects but they do not compound on repetition (like a DELETE). An operation can be idempotent but not safe: deleting a resource changes state, yet repeating it is harmless. Always test idempotency under concurrent conditions, because race conditions between parallel retries can break idempotent guarantees if the server-side deduplication store is not properly locked or atomic.
© RM Full Stack & AI Engineer · All guides · Roadmaps · Open the app