A user submits a payment, the connection hangs, and they click the button again. If your API is not idempotent, you charge the user twice. This is one of the most common payment integration disasters.
We implemented an Idempotency-Key header requirement for all transactional endpoints in NestJS. When a request arrives, the key is checked against a Redis lock. If the key exists, the API returns the cached response of the first transaction.
If the key does not exist, the API locks the key, processes the request, saves the response in Redis, and unlocks it. This protects transaction boundaries from network failures and double clicks.
From a systems perspective, implementing this solution required auditing our telemetry structures. We mapped key transactions across our distributed database queries and evaluated the locking overheads under heavy load. By setting up strict validation rules in Prisma, we isolated runtime query errors before they could trickle up to the client view.
Ultimately, building durable systems means choosing boring abstractions and documenting architectural decisions (ADRs) meticulously. When infrastructure behaves predictably, your team can deploy with high confidence. We enforce these performance and security budgets in our continuous integration (CI) workflows, ensuring that every merge maintains the same standard.