Idempotency

Idempotency means that repeating the same logical operation does not create additional externally observable effects after the first successful application.

Why Distributed Systems Need It

After a timeout, a client cannot assume that the server did nothing. The operation may have completed while the response was lost. Blindly repeating a create/write request can produce duplicate records or other side effects.

Natural business keys, idempotency keys or explicit state transitions can reduce that ambiguity. The transaction boundary that associates the key with the result is part of the design.

Not the Same as Exactly-Once Execution

An idempotent operation may physically run more than once. The guarantee is about the externally observed business effect. Audit records, external API calls or emitted messages need their own duplicate protection.

Relationship with Retry

Retry is safe only when the error class and operation semantics allow it. See Safe Retry Design in Critical Systems.

Related: Idempotency Key, Retry, Transactional Outbox.

Not the Same Guarantee as At-Most-Once

Idempotency does not limit how many times code may run; it constrains the observable result of repeating the same logical operation. At-most-once is a different delivery/execution property that attempts to prevent a second execution. A service may receive the same idempotency key twice and start internal work twice, yet still present one logical outcome if result recording and side effects are coordinated correctly.

An idempotency key should therefore not be treated as a casual cache key. Unless the key, request identity or parameter digest, and resulting state are associated within an appropriate transaction boundary, two concurrent requests can both believe they are the first. The normative HTTP concept of an idempotent method is defined in RFC 9110 §9.2.2; payments, messages, files, and other application side effects still need their own design. Applied context: Safe Retry Design.