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 redis = new