Why idempotency matters more than it looks

This is cheap to get right at the start and expensive to retrofit. Idempotency is easy to treat as a detail, and that is exactly why it is worth a few minutes of attention.

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.

Why this earns attention

Networks retry, so assume every request can arrive twice. This is the sort of thing that compounds, quietly, in both directions. It is worth deciding this deliberately rather than inheriting whatever the last person set up.

An idempotency key turns a hard problem into a simple one. There is a version of this that is over-engineered, and it is worth avoiding. Anything you cannot measure here, you are deciding by taste, which is fine as long as everyone knows it.

Common failure modes

Payment and order endpoints are where this matters most. The cost of getting this wrong is rarely visible on the day it happens. The practical test is whether someone new to the project could tell, in a minute, that it had been handled.

How to tell if yours is fine

The right architecture for a team of three is the wrong one for a team of thirty, and vice versa. 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.