Five mistakes teams make with idempotency

The advice here is unglamorous, which is probably why it gets skipped. These are the ones we run into repeatedly when we audit idempotency.

Architecture is the set of decisions that are expensive to reverse, which is the only reason they deserve the name. Most teams find the first pass takes an afternoon and the maintenance takes minutes a month.

Where it usually goes wrong

• Treating it as a launch task rather than an ongoing one
• Assuming someone else already owns it
• Networks retry, so assume every request can arrive twice
• An idempotency key turns a hard problem into a simple one
• Never checking whether the fix actually worked

Payment and order endpoints are where this matters most. None of that requires a large budget, only a decision and someone to own it. Write the reasoning down alongside the decision, because the reasoning is what changes first.

Where to go from here

In practice

Most systems fail at the seams rather than inside any one component. 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

None of this needs a rewrite. Most of it is a morning's work once someone decides to do it.