Idempotency for safe retries in HLD - System Design Exercise

Design: Idempotent Request Handling System

Design focuses on server-side idempotency handling for API requests. Client-side retry logic and network error handling are out of scope.

Functional Requirements

FR1: Allow clients to safely retry requests without causing duplicate effects

FR2: Ensure that repeated identical requests produce the same result as a single request

FR3: Support high throughput with minimal latency impact

FR4: Handle concurrent retries gracefully

FR5: Provide clear feedback to clients about request status

Non-Functional Requirements

NFR1: System must handle up to 10,000 concurrent requests with retries

NFR2: API response latency p99 should be under 200ms including idempotency checks

NFR3: Availability target of 99.9% uptime

NFR4: Idempotency keys must expire after 24 hours to limit storage

Think Before You Design

Questions to Ask

❓ Question 1

❓ Question 2

❓ Question 3

❓ Question 4

❓ Question 5

Key Components

API Gateway or Load Balancer

Idempotency Key Store (cache or database)

Application Server with idempotency logic

Persistent Database for final data storage

Response Cache for repeated requests

Design Patterns

Idempotency Key Pattern

Cache Aside Pattern

Write-Ahead Logging

Optimistic Concurrency Control

Reference Architecture

Client
  |
  | HTTP Request with Idempotency-Key header
  v
API Gateway / Load Balancer
  |
  | Forward request
  v
Application Server
  |
  | Check Idempotency Key Store
  |-- If key exists and completed: return stored response
  |-- If key exists and in progress: wait or reject
  |-- If key missing: process request
  |
  | Process business logic
  |
  | Store response and mark key as completed
  v
Persistent Database

Idempotency Key Store (Redis or DB) connected to Application Server

Components

API Gateway / Load Balancer

Nginx / AWS ALB

Route incoming requests and forward Idempotency-Key header

Idempotency Key Store

Redis or NoSQL DB

Store request states and responses keyed by Idempotency-Key

Application Server

Node.js / Java / Python

Check idempotency keys, process requests, store results

Persistent Database

PostgreSQL / MySQL

Store final business data and transaction records

Request Flow

1. Client sends request with unique Idempotency-Key header

2. API Gateway forwards request to Application Server

3. Application Server checks Idempotency Key Store for the key

4. If key exists and request completed, return stored response immediately

5. If key exists and request in progress, reject or wait to avoid duplicate processing

6. If key does not exist, mark key as in-progress and process request

7. After processing, store response and mark key as completed in Idempotency Key Store

8. Return response to client

9. Idempotency keys expire after 24 hours to free storage

Database Schema

Entities: - IdempotencyKey: key (string, PK), status (enum: in-progress, completed), response_data (json), created_at (timestamp), expires_at (timestamp) - BusinessEntity: id (PK), data fields... Relationships: - IdempotencyKey is independent but linked logically to BusinessEntity by request context

Scaling Discussion

Bottlenecks

Idempotency Key Store can become a hotspot under high concurrency

Application Server CPU and memory usage due to waiting or locking on keys

Database write latency affecting overall request processing time

Storage growth for idempotency keys over time

Solutions

Use a distributed in-memory cache like Redis Cluster for Idempotency Key Store to scale horizontally

Implement optimistic concurrency control or locking with timeouts to handle concurrent retries

Batch writes or use asynchronous processing to reduce database latency impact

Set TTL (time-to-live) on idempotency keys to automatically expire and clean up storage

Interview Tips

Time: Spend 10 minutes clarifying requirements and constraints, 20 minutes designing the architecture and data flow, 10 minutes discussing scaling and trade-offs, 5 minutes summarizing.

Explain why idempotency is important for safe retries and user experience

Describe how idempotency keys prevent duplicate processing

Discuss storage choices and expiration strategies for keys

Highlight concurrency challenges and how to handle them

Mention latency and availability targets and how design meets them