Skip to content
ROOT
STUB

Idempotency

The pattern: an operation that can be safely applied multiple times with the same effect as once. Critical when networks fail (retry) and producers may duplicate messages (Kafka, queues, distributed jobs). The classic primitives: idempotency keys, conditional writes, MERGE-style upserts, monotonic versioning.

The trade-off: producer cost vs. consumer simplicity. True idempotency (server-side dedup with persistent keys) is expensive. Best-effort idempotency (TTL’d keys, hash-of-payload) is cheap but not bulletproof. Many systems give the appearance of exactly-once via “at-least-once + idempotent consumer” — which works only if the consumer’s writes are themselves idempotent.

[Deepen Year 2 Phase 8 — once you’ve built sagas + retries + dedup, the pattern earns DEEP.]

  • Delivery semantics — idempotency is the consumer half of “exactly-once-ish.”
  • Two-phase commit vs. sagas — saga compensations only work if every step (and its inverse) is idempotent.
  • Replication — log-replay during failover demands idempotent apply.
  • Control loops — reconciliation is idempotency at the design level: re-running the loop must not drift.
  • Append-only log — offsets + dedup keys are the storage substrate.

First touched in Year 1 Phase 3 (database upserts); reinforced in Year 1 Phase 5 (Go retry loops); promoted to DEEP in Year 2 Phase 8 once sagas + retries + dedup are operational.