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

Idempotency and Client Responsibilities

Clarify the client's role in generating unique keys and deciding when to retry with the same key.

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:

  1. Generating unique idempotency keys – Typically a UUID or similar globally unique identifier
  2. Storing the key locally for potential retries
  3. 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:

  1. Generate key before first attempt
  2. Store key with request context
  3. On failure, check if retry is appropriate
  4. Reuse key for legitimate retries
  5. 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.