Idempotency
Idempotency is the property that repeating an operation yields the same result as doing it once, enabling safe retries in distributed systems.
Idempotency describes an operation that can be applied many times without changing the result beyond the first application. In API design, it is the foundation for safe retries when network failures make it unclear whether a request succeeded.
How It Works
In HTTP, GET, PUT, and DELETE are defined as idempotent: repeating them leaves the resource in the same final state. POST is not idempotent by default, because each call typically creates a new resource. To make POST safe to retry, APIs accept an idempotency key, a unique client-generated identifier sent in a header. The server records the result for that key and returns the stored response if the same key arrives again, instead of performing the work twice.
Implementing this requires durable storage of keys and their outcomes, with an expiry policy, plus careful handling of concurrent retries of the same key.
Why It Matters
Networks are unreliable. A client may send a request, receive no response, and not know if it was processed. Without idempotency, retrying risks duplicate charges, duplicate orders, or double-counted events. With it, the client can retry confidently.
Idempotency is essential for payment APIs, message consumers, and webhook receivers, where exactly-once effects are needed on top of at-least-once delivery. It is a core building block of resilient distributed systems and works hand in hand with retry policies and deduplication.
Related Terms
Idempotency underpins safe retries in REST APIs and webhook handlers, and interacts with how clients respond to rate limiting and transient errors.