Idempotency Key Storage and Lookup
You'll learn how to efficiently store and retrieve idempotency keys to prevent duplicate operations.
The Core Problem
When a client sends an idempotency key with a request, your server needs to check if that key has been seen before. If it has, you must return the cached result instead of re-executing the operation. This means you need a fast, reliable way to store keys alongside their operation results.
Storage Requirements
Think of idempotency key storage like a receipt system at a returns counter. When someone returns an item, the clerk checks if that receipt was already used. The system needs to:
- Store the key (receipt number) with the operation outcome
- Look up keys quickly to avoid slowing down requests
- Track operation status (pending, completed, failed)
- Persist results to return them for duplicate requests
Choosing a Data Store
You need a fast key-value store for this. In-memory stores like Redis are ideal because:
- Lookups happen in O(1) time
- Network latency is minimal
- You can set automatic expiration (matching your idempotency time window)
- They support atomic operations to prevent race conditions
The stored value typically includes:
- Original request parameters (to verify it's truly the same request)
- Operation status (in-progress, succeeded, failed)
- Response payload (if completed)
- Timestamp (for expiration)
Lookup Flow
- Client sends request with
Idempotency-Key: abc123 - Server checks Redis:
GET idempotency:abc123 - If found → return cached result
- If not found → execute operation, store result with key
Key Takeaway: Idempotency requires a fast, persistent key-value store (typically Redis) to efficiently track which operations have been performed and cache their results for duplicate requests.