Idempotency

An operation is idempotent when performing it multiple times has the same effect as performing it once. In distributed systems, idempotency is what makes retries safe, so that a client or broker can resend a request after a timeout without causing duplicate side effects such as a double charge.

Some operations are naturally idempotent, and some must be made so:

• Naturally idempotent: "set balance to 100" or an HTTP PUT that overwrites a resource; repeating it changes nothing after the first success.
• Not idempotent: "add 100 to balance" or an HTTP POST that creates a new record; repeating it duplicates the effect.

The standard technique is an idempotency key: the client attaches a unique identifier to the request, and the server records the key with the result. If the same key arrives again, the server returns the stored result instead of redoing the work.

Idempotency is the safety net for at-least-once delivery in message queues and publish-subscribe, and it is a common building block inside distributed transactions, where compensating steps may be retried.

Idempotency keys let you retry freely, but the server must store processed keys and their results, which costs memory or a database table and needs a time-to-live so it does not grow forever. Deduplication windows are finite, so extremely delayed duplicates can slip through. There is also a concurrency concern: two copies of the same request arriving at once must be serialized, usually with a unique constraint or a lock on the key.

• State the failure that motivates it: a lost response leaves the client unable to tell success from failure.
• Propose an idempotency key with a stored result and a TTL as the default design.
• Map HTTP verbs to their idempotency to sound precise; POST is the odd one out.
• Mention that duplicate concurrent requests need a unique constraint or lock, not just a lookup.