Idempotency, explained without the jargon

It comes up on almost every project, usually later than it should. Here is idempotency without the vocabulary that usually surrounds it.

Most systems fail at the seams rather than inside any one component. If two people in the business would answer this differently, that gap is the actual problem.

The short version

Networks retry, so assume every request can arrive twice. Where this goes wrong is almost never a lack of knowledge. If it only works because one person remembers to do something, it does not work yet.

Why people complicate it

Most of the confusion comes from tooling rather than from the idea itself. In practice this is a scheduling problem more than a technical one.

An idempotency key turns a hard problem into a simple one. The reasoning matters more than the rule, because the rule has exceptions. It is worth deciding this deliberately rather than inheriting whatever the last person set up.

Turning this into a decision

Payment and order endpoints are where this matters most. In practice this is a scheduling problem more than a technical one. Doing this properly once is usually cheaper than doing it approximately three times.

The short version

Architecture is the set of decisions that are expensive to reverse, which is the only reason they deserve the name. Three things worth confirming about idempotency before you move on:

• Someone can say what the current setup is without going to look
• Networks retry, so assume every request can arrive twice — and you know whether that is true here
• There is a way to tell whether the last change to this helped

The point is not perfection, it is knowing which of these you have consciously chosen to skip.