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.