Idempotency Keys
You'll learn: How client-provided identifiers guarantee that operations execute exactly once, even when requests are duplicated.
What Are Idempotency Keys?
An idempotency key is a unique identifier that a client generates and sends with each request. The server uses this key to recognize duplicate requests and ensure the operation executes only once, no matter how many times the same request arrives.
Think of it like a ticket number at a coffee shop. If you hand in the same ticket twice, the barista checks the system and says "You already got this coffee!" instead of making a second one. The ticket number is your idempotency key.
How They Work
When a client makes a critical request (like charging a payment), it generates a unique key—often a UUID—and includes it:
POST /payments
Idempotency-Key: 8f3e7a2b-91c4-4d5e-a8f6-1234567890ab
{ "amount": 50, "user_id": 123 }
The server:
- Checks if it's seen this key before
- If new: executes the operation and stores the key with the result
- If duplicate: returns the stored result without re-executing
This prevents the double-charge problem even when networks fail, clients retry, or load balancers send duplicate requests.
Why Client-Provided?
The client generates the key because only the client knows its retry intentions. If the server generated keys, retries would look like new requests.
Key Takeaway: Idempotency keys are client-provided unique identifiers that allow servers to detect and safely handle duplicate requests, ensuring operations execute exactly once regardless of retries or network failures.