Idempotency in practice: making retries safe

You send a request to create a payment. The connection drops before the response comes back. Did it work? Without idempotency, retrying risks charging twice; not retrying risks losing the payment. Neither is acceptable.

One key, one outcome

Attach a unique idempotency key to the request. The first time we see it, we process it and record the result. Every later request with the same key returns that stored result instead of doing the work again.

await pay.payments.create(
  { amount: 36000, currency: 'XAF' },
  { idempotencyKey: order.id }
)

The key insight: derive the key from something stable in your domain, like an order id. Then a retry storm produces exactly one payment, no matter how many times the request lands.