Idempotency and Exactly-Once Processing

In any distributed system, messages get retried and delivered more than once — a response is lost, a consumer crashes after acting but before acknowledging, a client times out and resends. Idempotency makes a repeated operation safe: doing it twice has the same effect as doing it once. It is the practical substitute for true exactly-once delivery, which is impossible over an unreliable network.

The fundamental result: you cannot guarantee a message is delivered exactly once across a network that can drop packets and crash nodes. You get at-most-once (may lose) or at-least-once (may duplicate). The industry answer is at-least-once delivery + idempotent processing = effectively exactly-once: duplicates still arrive, but they no-op. Source: compiled from delivery-semantics literature

Mechanisms

• Idempotency key — the client attaches a unique key per logical operation; the server records "key → result" and on a repeat returns the stored result without re-executing. The standard for POST/payments. Source: Stripe idempotency-key design
• Natural idempotency — design the operation so repetition is harmless: SET balance = 100 (vs ADD 100), upserts, PUT to a known id.
• Dedup store — consumers record processed message ids (with a TTL) and skip seen ones.
• Fencing tokens — monotonic tokens reject stale/duplicate writers after a timeout (guards against a paused node resuming).
• Conditional writes — compare-and-set / version checks so a replay with an old version is rejected.

In message systems

Log/queue systems mostly run at-least-once; correctness comes from idempotent consumers, not from the broker. Transactional/outbox patterns tie "produce a message" and "commit a DB change" into one atomic step to avoid the dual-write problem.

Design implications

• Make side effects idempotent at the boundary. Sending email, charging cards, calling external APIs — each needs a key or a dedup check, or retries double-fire.
• Keys need a retention window. Store them long enough to outlive realistic retry windows; GC the rest.
• Pairs with sagas. Compensations are retried too, so they must be idempotent and ideally commutative.
• Append-only helps. Event logs dedup by event id; projections fold idempotently.

This is foundational to Kevin's Billing Ledgers (an idempotency key per charge prevents double-billing — a real exploit class), to webhook delivery (receivers must dedup retried deliveries), and to durable agents (a step may run twice across a crash).

Architecture Position

---

Timeline

• 2026-07-01 | Architecture category refresh added this page to the Safety and observability family, linked it to Architecture System Map, and kept it standalone because it owns this boundary: Retry-safe side effects and exactly-once semantics as an illusion built from idempotency. Source: User request, 2026-07-01

• 2026-06-02 | Page created. Captured the impossibility of network exactly-once, at-least-once + idempotent = effectively-once, the mechanism catalog (keys, natural idempotency, dedup, fencing, CAS), the message-system + outbox pattern, and grounding in billing/webhooks/durable agents. Source: compiled from delivery-semantics literature; Stripe idempotency-key design