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

Request Token Generation and Management

Best practices for generating, storing, and expiring idempotency tokens across distributed clients and servers.

Request Token Generation and Management

What You'll Learn

You'll learn how to safely generate, store, and expire idempotency tokens across distributed clients and servers to prevent duplicate operations.

The Core Idea

When clients retry requests (due to network failures or timeouts), they need a way to prove "this is the same request, not a new one." That proof is an idempotency token (also called a request token or idempotency key). Managing these tokens correctly ensures your system can detect and handle duplicates without expensive or dangerous re-execution.

Think of it like a coffee shop loyalty card with a unique stamp for each purchase. If you accidentally hand over the same stamped card twice, the barista recognizes it and doesn't charge you again.

Generation Best Practices

Client-side generation is preferred. The client creates a unique token (typically a UUID or GUID) before making the request. This ensures the same token accompanies all retries of that logical operation.

POST /payments
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Tokens should be:

  • Globally unique (UUIDs work well)
  • Unpredictable (avoid sequential IDs)
  • Scoped appropriately (per user, per account, etc.)

Storage and Lookup

Servers must store tokens with the operation result. Use fast key-value stores like Redis with the token as the key and response metadata as the value.

Expiration Strategy

Tokens shouldn't live forever—they consume storage and may leak information. Set expiration windows (e.g., 24-72 hours) based on your retry policy and business requirements. After expiration, the same token is treated as a new request.

Key Takeaway:
Generate idempotency tokens client-side using UUIDs, store them server-side with response data, and expire them based on reasonable retry windows to balance safety and resource efficiency.