BeCuriouzLearn something new every day
Why every serious payment API begs you to send a random string
💡 An idempotency key lets a client safely retry a request over an unreliable network without risking the operation happening twice.
In a classic Stripe engineering post, Designing robust and predictable APIs with idempotency, Brandur Leach starts with an uncomfortable truth: networks are unreliable. Requests time out, connections drop, and a caller often has no idea whether the server actually processed a request or the response just vanished on the way back. For a payments API, that ambiguity is dangerous — retry a charge blindly and you might bill someone twice.
The fix is the idempotency key: a unique string (like a random UUID) the client generates and attaches to a request. The server records the outcome against that key. If the same key arrives again — because the client retried after a timeout — the server returns the stored result instead of doing the work a second time. Idempotency means an operation can be repeated many times but takes effect only once.
This flips responsibility in a useful way. Clients become free to retry safely and aggressively without fear of duplicates, and the API stays predictable even when the network misbehaves. The pattern turns a scary, one-shot operation into something you can attempt again and again until you get a clear answer — which is exactly what you want when real money is on the line.