Why idempotency: making retries safe

Bea hits “Pay Now” on a checkout page. Her wifi drops before the response arrives. She presses again. The server has no way to tell the second click from the first — so it charges her twice.

The network guarantee problem

The internet guarantees at-least-once delivery if the client retries until it sees an answer, and at-most-once if it never retries. Neither is acceptable on its own:

• At-most-once — a payment that never finished because the client gave up.
• At-least-once without dedup — a double charge.

The gap between them is the application’s job to close. The tool is idempotency.

What an idempotency key is

An idempotency key is a client-generated opaque string — typically a UUID v4 (36 characters) — sent in the Idempotency-Key HTTP request header. The client picks one key per logical operation, not per request. Every retry of the same operation reuses the exact same key.

The server uses the key as a primary token to answer: “have I already processed this?” If yes, it replays the original response without re-running the business logic. If no, it processes and records the result.

The metaphor: envelope + clipboard

Imagine sending money via courier. You mark the envelope “Order #A7-payment” and tell the courier: “If this envelope was already delivered, do not deliver another.” On every retry you write the same order number on the new envelope. The recipient checks a clipboard (the idempotency cache) and either delivers the envelope or says “already done — here is the receipt.”

The clipboard remembers. Without it, every envelope looks new.

HTTP convention

Stripe popularized the Idempotency-Key header in 2014. Square, PayPal, Adyen, and the IETF draft draft-ietf-httpapi-idempotency-key-header all follow the same shape. RFC 9110 §9.2.2 lists which HTTP methods are idempotent by spec (GET, HEAD, PUT, DELETE, OPTIONS) — POST is not, which is exactly why the header exists.