Idempotency is not optional when you are moving money

A network request that times out has not failed. It has become unknown. The server may have processed it completely, partially, or not at all, and the client has no way to tell which.

For most APIs this is an annoyance. For a payments API it is the difference between paying a supplier once and paying them twice.

Retrying is not optional either

The obvious response is to not retry. This is worse. A payroll run that silently drops a payment because the client gave up is a person who does not get paid, and nobody finds out until they complain.

So the client must retry, and the server must make retrying safe. That is what an idempotency key does.

How the key works

You generate a key that identifies the intent, not the attempt. For a March payroll run, something like payroll-2026-03 plus the employee identifier. The same intent always produces the same key.

The first request with that key creates the payout and stores the response against the key. Every later request with the same key returns that stored response without doing anything else. Retry as many times as you like: one payout exists.

The mistakes we see

Generating the key at the moment of sending, using a fresh random value each time. This makes every retry a new intent, which is exactly the thing you were trying to prevent.

Reusing a key across genuinely different payments, usually by keying on something insufficiently specific like the date alone. Now the second payment silently returns the first one's response and never happens.

Both failures are quiet. Neither produces an error. This is why we retain keys for 72 hours rather than 24, so replaying a failed run the next working day still behaves.

What we guarantee

Every write endpoint accepts an Idempotency-Key header. Same key and same body returns the original response. Same key and a different body returns an error rather than quietly doing the wrong thing.

That last part matters. Silently ignoring a changed body would turn a client bug into a payment your customer never intended.