Idempotency Keys: Why 'Send Once' Is Harder Than It Sounds

In a distributed system, the network can fail *after* a payment has been successfully processed but *before* the confirmation reaches the client. Without idempotency, a retry creates a double charge.

How we handle it

Every money-touching operation at Sente requires a **UUIDv4 Idempotency-Key** generated by the client. The server:

1. Acquires a **Redis distributed lock** on the key.

2. Checks the **Postgres idempotency result store** — if a previous result exists, it replays it exactly.

3. If not, processes the request and stores the result **atomically** with the transaction.

If a client sends the same key with a different body, we return `IDEMPOTENCY_CONFLICT` — because the client may have retried with stale data.

This is one of those problems that sounds trivial until you're responsible for other people's money. Then it becomes the most important 30 lines of code in your system.