Idempotency

Overview

Idempotency means that performing the same operation multiple times produces the same result as performing it once. This is critical in distributed systems where operations may be retried due to network failures or timeouts.

Non-idempotent operation: Charge $10 (running twice charges $20) Idempotent operation: Set balance to $100 (running twice sets to $100 both times)

Key Concepts

Idempotent

Operation that can be applied multiple times without changing the result beyond the initial application. Example: PUT, DELETE.

Non-idempotent

Operation that produces different results when repeated. Example: POST (creates new resource each time).

Idempotency Key

Unique identifier for a request. Server uses this to detect duplicate requests.

How It Works

Without Idempotency:

Client: "Charge $10"
Server: Charges $10, but response lost in network
Client retries: "Charge $10"
Server: Charges another $10
Total charged: $20 (Wrong!)

With Idempotency Key:

Client: "Charge $10, idempotency_key=abc123"
Server: Charges $10, stores key=abc123
Network fails, client retries
Client: "Charge $10, idempotency_key=abc123"
Server: Sees same key, returns original response
Total charged: $10 (Correct!)

Implementation:

Client generates unique key (UUID)
Server checks if key exists in database
If exists: return cached response
If new: process, store key + response
Keep keys for 24 hours

Use Cases

Payment processing (ensure charge exactly once)

Order creation (prevent duplicate orders)

API calls over unreliable networks

Background job processing

Message queue consumers

Distributed transactions

Best Practices

Use UUIDs for idempotency keys

Store keys in database with original response

Set reasonable TTL (24-72 hours typical)

Make POST requests idempotent when possible

Design operations to be naturally idempotent

Document which endpoints require idempotency keys

Return 409 Conflict if key exists with different parameters

Clean up old idempotency keys periodically

Interview Tips

What Interviewers Look For

•
Explain why idempotency is critical: network failures, timeouts, retries are common
•
Give concrete example: payment processing
•
Discuss HTTP methods: GET, PUT, DELETE are naturally idempotent, POST is not
•
Mention idempotency keys as implementation technique
•
Talk about storage and TTL for idempotency keys
•
Explain the difference between idempotent and safe operations
•
Discuss at-least-once vs exactly-once delivery in message queues