Idempotency Tokens in Retry Logic
What you'll learn: How idempotency tokens prevent duplicate operations when retrying failed requests in distributed systems.
The Problem Without Tokens
When a network request fails or times out, you often can't tell if the server processed it or not. If you retry blindly, non-idempotent operations (like creating a payment or order) might execute twice. The server has no way to recognize "I've seen this exact request before."
How Idempotency Tokens Solve This
An idempotency token (or key) is a unique identifier the client generates and includes with each request. When retrying, the client sends the same token again.
The server tracks tokens it has seen:
- First attempt: Token is new → process the request, store the token and result
- Retry: Token matches a stored one → return the cached result without re-executing
Think of it like a ticket number at a deli counter. If you ask "Did I get order #42?" they can check their records. Without a ticket number, they'd have no way to know if you already received your order.
In Practice with Retries
When your retry logic kicks in (using exponential backoff with jitter, as you've learned), you keep the same idempotency token across all retry attempts for that operation. Each unique business operation gets its own token—but retries of the same operation reuse it.
Client generates: token = "uuid-abc-123"
Attempt 1: POST /payments {token: "uuid-abc-123", amount: 100} → timeout
Attempt 2: POST /payments {token: "uuid-abc-123", amount: 100} → success
Attempt 3: POST /payments {token: "uuid-abc-123", amount: 100} → returns cached result
The server only charges once, despite three attempts.
Key Takeaway: Combining idempotency tokens with retry logic ensures that retries are safe—clients can aggressively retry failed requests without fear of creating duplicate charges, orders, or other side effects.