Idempotency in a betting API, and why the key is yours

The failure everybody meets

You send a bet. The connection times out. You do not know whether it landed.

Without idempotency you have two bad options: retry and risk charging twice, or do not retry and risk a player who lost money on a round that never opened. Both happen, and both generate the kind of support ticket that takes a week.

Who mints the key

Some APIs generate an id and return it. That is fine until the response is the thing that goes missing, at which point you cannot retry safely because you never learned the id.

So the transaction id is yours. You generate it, you send it, and it is the key the movement is recorded under on both sides. A retry is the same request byte for byte, and it is safe by construction rather than by convention.

What a correct replay does

A replayed transaction returns the same result as the first one and moves no money. Not an error, not a duplicate record, not a 409 the caller has to interpret — the same answer.

That property has to hold in both directions. We hold it for calls you make to us, and we require it of your wallet for the calls we make to you, because a chain is only as idempotent as its least careful link.

The three cases to test

• Immediate replay. Same id twice in a row, one movement.
• Delayed replay. Same id an hour later, after the round has settled. Still one movement.
• Concurrent replay. The same id twice at once, which is what an aggressive retry actually looks like. Still one movement — this is the one that catches implementations relying on a read-then-write instead of a unique constraint.

The third is the one most integrations fail, and it fails only under load, which is to say in production.