A mobile client calls POST /payments and the connection times out. It doesn't know if the charge happened. How do idempotency keys make the retry safe?

The client sends the same unique key with the first request and with every retry. The server uses this key to make sure the payment runs only once.

An idempotent operation gives the same result if you run it once or many times.

On the client:

• Create one unique key, such as a UUID, for each logical operation. For example, one key for "pay this order".
• Send it in an Idempotency-Key header.
• On a retry, send the same key again.

On the server:

• Store the key with a fingerprint of the request. A fingerprint is a hash of the request body, so the server can tell if two requests are the same.
• When processing finishes, also store the response status and body.
• When a request arrives with a key the server already knows, it does not charge again. It returns the stored response.
• If the first request is still running, the server returns an error such as 409, so the client retries later.
• If the same key arrives with a different body, the server rejects the request.

Safety details:

• Write the key record atomically with the payment, or lock it with a unique constraint in the database. Atomically means both are saved together or neither is. This stops two retries that arrive at the same time from both passing.
• Scope keys per client, so two clients can't clash on the same key.
• Expire keys after a retention window, such as 24 hours.