What is an idempotency key and how does it prevent duplicate requests?
Understand idempotency keys in REST APIs: how a unique client token prevents duplicate requests and duplicate charges, with headers and retry examples.
Expected Interview Answer
An idempotency key is a unique client-generated token sent with a request so the server can detect and safely ignore retries, returning the original result instead of performing the operation twice.
The client sends a header such as Idempotency-Key: <uuid> with a non-idempotent request like POST /payments. The server stores the key with the outcome of the first successful call. If the same key arrives again — after a timeout, network drop, or user double-click — the server recognizes it, skips reprocessing, and replays the stored response. Keys are scoped per endpoint and given a retention window, which is why payment and order APIs rely on them for exactly-once effects.
- Prevents duplicate charges and orders
- Makes retries safe over unreliable networks
- Enables exactly-once effects on POST
- Simplifies client retry logic
- Protects against double-click submissions
AI Mentor Explanation
An idempotency key is like a unique delivery number the scorer writes before recording a ball. If the signal is repeated because the umpire's call was unclear, the scorer sees the same delivery number and refuses to add the runs twice. The retry is acknowledged, yet the scorebook stays correct because that exact ball is only ever counted once.
Step-by-Step Explanation
Step 1
Client generates a key
Before a POST, the client creates a unique token (usually a UUID) and sends it in an Idempotency-Key header.
Step 2
Server looks up the key
On receipt, the server checks its idempotency store for that key scoped to the endpoint and account.
Step 3
First request path
If the key is new, process the operation, then persist the key together with the response status and body.
Step 4
Retry path
If the key already exists with a completed result, skip processing and replay the stored response verbatim.
Step 5
Handle in-flight and expiry
Return 409 or wait if a request with the same key is still processing, and expire stored keys after a retention window.
What Interviewer Expects
- Definition of idempotency and why POST needs help
- Client-generated unique key in a header
- Server-side storage of key plus response
- Correct handling of concurrent and expired keys
- Real use case such as payments or orders
Common Mistakes
- Confusing idempotency keys with authentication tokens
- Letting the server generate the key instead of the client
- Not storing the original response to replay it
- Ignoring concurrent in-flight requests with the same key
- Never expiring keys, growing the store unbounded
Best Answer (HR Friendly)
“An idempotency key is a unique code a client attaches to a request so the server can tell if it has seen that exact request before. If a payment is accidentally sent twice, the server recognizes the code and processes it only once, preventing duplicate charges.”
Code Example
POST /v1/payments
Idempotency-Key: 5f2c9a1e-7b3d-4a10-9c88-1f2e3d4c5b6a
Content-Type: application/json
{ "amount": 4200, "currency": "usd", "source": "card_abc" }
// First call -> charges once, stores key + response
// Same key resent after timeout -> server replays original:
HTTP/1.1 200 OK
{ "id": "pay_991", "amount": 4200, "status": "succeeded" }Follow-up Questions
- How long should idempotency keys be retained?
- How do you handle two concurrent requests with the same key?
- Are GET and PUT naturally idempotent, and why?
- Where would you store keys for a distributed API?
- What happens if the request body differs but the key repeats?
MCQ Practice
1. Who should generate the idempotency key?
The client generates a unique key so retries of the same logical request carry the same key for the server to recognize.
2. What does the server do when a completed key is seen again?
It replays the previously stored response instead of performing the operation a second time.
3. Which method most needs idempotency keys?
POST is not naturally idempotent, so keys give it exactly-once effects; GET, PUT and HEAD are already idempotent.
Flash Cards
What is an idempotency key? — A unique client-generated token that lets the server detect and safely ignore duplicate requests.
Which header carries it? — Idempotency-Key, typically holding a UUID.
What does the server store? — The key plus the original response status and body, so retries can be replayed.
Why does POST need it? — POST is not naturally idempotent, so a key gives it exactly-once behavior on retries.