Idempotency: what to get right first

The advice here is unglamorous, which is probably why it gets skipped. If you only fix one thing about idempotency this quarter, make it the first item below.

Most systems fail at the seams rather than inside any one component. It is worth deciding this deliberately rather than inheriting whatever the last person set up.

Start here

Networks retry, so assume every request can arrive twice. Small and consistent beats large and occasional here. Doing this properly once is usually cheaper than doing it approximately three times.

Then this

An idempotency key turns a hard problem into a simple one. In practice this is a scheduling problem more than a technical one. Most teams find the first pass takes an afternoon and the maintenance takes minutes a month.

Eventually

Payment and order endpoints are where this matters most. In practice this is a scheduling problem more than a technical one. Assume whoever inherits this will have half your context and none of your patience.

The short version

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
• Payment and order endpoints are where this matters most — 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.