Idempotency and Client Responsibilities
What You'll Learn
You'll understand what the client must do to ensure idempotent behavior and when to reuse versus regenerate idempotency keys.
The Client's Role in Idempotency
While servers implement idempotency logic, clients drive the process. The client is responsible for:
- Generating unique idempotency keys – Typically a UUID or similar globally unique identifier
- Storing the key locally for potential retries
- Deciding when to retry with the same key versus generating a new one
When to Reuse the Same Key
The client should retry with the same idempotency key when:
- The request failed due to network issues (timeout, connection reset)
- The server returned a transient error (503 Service Unavailable, 429 Rate Limited)
- The request's intent hasn't changed (still trying to complete the same operation)
Think of it like mailing a package: if it gets lost in transit, you resend the same tracking number so the recipient knows it's not a duplicate order.
When to Generate a New Key
Use a different idempotency key when:
- The previous request succeeded (confirmed by the server)
- The user initiates a genuinely new operation
- The request parameters change meaningfully
If you're ordering a second coffee, that's a different transaction—use a new key.
Client Implementation Pattern
The client maintains a request lifecycle:
- Generate key before first attempt
- Store key with request context
- On failure, check if retry is appropriate
- Reuse key for legitimate retries
- Discard key only after confirmed success or intentional abandonment
Key Takeaway: The client owns idempotency key generation and lifecycle management; the key should remain constant across all retry attempts for the same logical operation but change for genuinely new requests.