← Concepts
Reliability·3 min read

Idempotency

An operation you can safely apply more than once and get the same result: the foundation of every retryable system.

First time reading this? Start here

Plain English: 'set my balance to $100' is idempotent, so running it twice doesn't double-set anything. 'Add $10 to my balance' is NOT, so running it twice charges me extra. Networks lose responses constantly, so any operation that matters has to be designed so a retry doesn't break things.

Used in:Payment GatewayApache KafkaNotification System
What it is

A property of an operation: F(x) == F(F(x)) == F(F(F(x))). 'Set balance to $100' is idempotent. 'Add $10 to balance' is not: retry it and the user is overcharged. Idempotency is what makes networks tolerable. Networks lose responses, timeouts lie, retries happen, and without idempotency, every retry is a potential bug.

The problem it solves

Every distributed system has at-least-once delivery somewhere. A request times out, the client retries, the server processes both, and now what? Without idempotency, you get duplicate charges, doubled inventory adjustments, duplicate emails. With idempotency, the second request is a no-op or returns the cached result.

How it works

Three common patterns: (1) Idempotency keys, where the client sends a unique key with each request; the server records it and returns the cached response on retry (Stripe's model). (2) Natural idempotence, where you design the operation so it's inherently safe to repeat (PUT, upserts, 'set' instead of 'add'). (3) Versioned writes, where you include an expected version; the second write fails the optimistic-lock check and is a no-op.

Why use it
What it costs you
Where it shows up in our architectures
Gotchas

Your notes

Private to you