Idempotency

When a customer places an order on the Composable Commerce Platform, seven events need to happen in sequence across four independent services: Order created → Payment authorized → Stock reserved → Fulfillment triggered → Notification sent → Loyalty points awarded → Shipping label generated. Any of these can fail. The network can fail. The database can fail. A third-party payment gateway can time out. Without a reliability mechanism, a 2% failure rate on any step means 2% of all orders are stuck in an inconsistent state, requiring manual intervention. ...

Answer-first: API idempotency ensures that retrying an identical request (same Idempotency-Key) never produces additional side effects beyond the first execution. This is foundational for payment APIs where network timeouts force client retries, and a duplicate execution would mean a double charge. Prerequisite: Part 7 of the System Design Masterclass. Read Part 6: Distributed Locks — concurrent duplicate request blocking relies on the same mutual exclusion primitives. What You’ll Learn That AI Won’t Tell You Payload Reuse Vulnerability: How Stripe prevents malicious request payload tampering on existing keys using SHA-256 request body hashes in Redis. SetNX Lock Lifetime Math: Why setting a lock TTL without a auto-extension renewal thread leads to double-charge execution gaps. Response Record Memory Leak: The memory consumption strategy of caching full HTTP headers and response body data under high-throughput request rates. What Is an Idempotency Key? Key Concept: An Idempotency Key is a unique token — typically UUID v4 — generated by the client and attached as an Idempotency-Key HTTP header. The server uses this key to detect duplicate requests: if the key has been seen before, return the cached response from the first execution without re-executing the handler. ...

Prerequisite: Before reading this chapter, please ensure you have read the previous article in this series: Chapter 6: API Gateway vs Service Mesh in Microservices Architecture. In E-commerce or Fintech, the ultimate nightmare is not a system crash, but charging a customer twice for a single order. This is usually caused by network lag, an impatient user double-clicking “Pay”, or automated app retry logic. The mandatory solution for any transactional API (Payment/Order) is Idempotency. ...