Skip to content
API Design Learn/Production REST II: Correctness & Scale
Browsing as a guest. Sign in to save your progress and earn XP as you complete chapters.

Idempotency Keys

4 min read

You'll learn to

  • -Explain the timeout problem: the request may have succeeded even though the client never heard back
  • -Make a POST safe to retry with an Idempotency-Key, and watch a retry return the original answer
  • -Handle a reused key with a different body (409), and keep keys for a bounded time

GET, PUT and DELETE are idempotent by the HTTP rules: doing them twice is the same as once. POST is not, and that becomes a real production problem the moment a network timeout happens. The client never received a response, but the request may well have succeeded on the server. Should it retry and risk creating the thing, or charging the payment, twice?

An Analogy: Pressing the Elevator Button Again

You press the call button, nothing lights up, so you press it again. A sensible elevator system does not send two elevators. It recognizes it is the same call. An idempotency key is how a payment API recognizes "this is the same request again", not "someone wants to pay twice".

The Idempotency-Key Header

A client-generated key makes an unsafe POST retry-safe
POST /payments
Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7
{"amount": 4999, "currency": "usd", "customer_id": 42}

HTTP/1.1 201 Created
{"id": "pay_501", "status": "succeeded"}

# The exact same request, retried after a timeout - same key, same body:
POST /payments
Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7
{"amount": 4999, "currency": "usd", "customer_id": 42}

# Server recognizes the key was already processed - returns the ORIGINAL
# result again, without charging a second time:
HTTP/1.1 201 Created
{"id": "pay_501", "status": "succeeded"}

The client generates a unique key, usually a UUID (a long random-looking identifier), once per logical operation, before the first attempt. It sends the same key on every retry of that same operation. The server stores a mapping from key to the result it already produced. A retry with a key it has seen gets the stored result back, without running the action again.

The demo plays the whole story. The first attempt succeeds, but the reply is lost. The client retries with the same key and gets the same answer, and the money moves once. Then the same key arrives with a different amount, and a brand new key arrives for a genuinely new payment.

Press Run: the retry is answered from storage, and the amount is charged once

What Happens on a Body Mismatch

The same key, but a genuinely different request body - a real conflict
POST /payments
Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7
{"amount": 9999, "currency": "usd", "customer_id": 42}

HTTP/1.1 409 Conflict
{"error": "Idempotency-Key already used with a different request body"}

A key that shows up again with a genuinely different body is not a legitimate retry. It is either a client bug, such as accidentally reusing a key, or an attempt to piggyback a different operation on a used key. Returning 409 surfaces the mismatch. Silently processing the new body, or silently returning the old result, would hide a real bug.

A Reasonable Retention Window, Not Forever

Keys do not need to be stored forever. A retry that matters happens within seconds or minutes of the original, not months later. A bounded window, commonly 24 hours, covers realistic retries without an ever-growing key table.

This is the same pattern as the idempotency key in the database money chapter. Here it is the API-facing half of the same problem: stopping a network-level retry from becoming a duplicate business operation.

Interview Signal is part of Pro

See a real weak answer next to a real strong one for this exact topic.

Quiz is part of Pro

Test what you just read with a short quiz, and bank the XP.

Ready to Build This?

Design Idempotency Shield in the API Design Lab's Production Patterns act.

Discussion0

Join the Discussion

Sign in to leave comments, reply to others, or like insights.

Sign In to ScaleDojo

No comments yet. Be the first to start the thread!