Designing Idempotent APIs: Why Your POST Endpoint Needs to Handle Duplicates

Designing Idempotent APIs: Why Your POST Endpoint Needs to Handle Duplicates A user clicks Buy. Nothing happens. They click again. Two charges. What Idempotency Means Same request N times = same result. GET, PUT, DELETE are idempotent. POST is not. Why This Matters Network retries : Mobile app retries on timeout. Server already processed the first request. Load balancer retries : Upstream timeout triggers retry to different backend. User double-clicks : Button not disabled fast enough. Without idempotency, each retry creates duplicates. The Idempotency Key Pattern Client generates a UUID and sends it as a header. Server checks before processing. POST /api/orders Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000 {"product_id": "prod_123", "quantity": 2} Server: check if key exists in Redis. If yes, return cached response. If no, process and cache. Express Middleware Implementation import { Request , Response , NextFunction } from " express " ; import Redis from " ioredis " ; const r