Course contentsShow
← System Design
Lesson 1011 of 1,91926. Idempotency and RetriesFree lesson

Idempotency Key Storage and Lookup

Store idempotency keys with operation results in a fast data store to detect and handle duplicate requests efficiently.

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

  1. Client sends request with Idempotency-Key: abc123
  2. Server checks Redis: GET idempotency:abc123
  3. If found → return cached result
  4. 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.