Idempotency Key

ELI5 — The Vibe Check

An idempotency key is a unique ID you attach to a request so the server knows if it's a duplicate. If your payment request gets retried because of a network glitch, the key prevents charging the customer twice. It's like a receipt number — 'I already processed this one.'

Real Talk

An idempotency key is a unique client-generated identifier sent with non-idempotent requests (typically POST) to ensure they're processed exactly once. The server stores the key and response, returning the cached response for duplicate requests. Critical for payment processing, order creation, and any operation where retries could cause unintended side effects.

Show Me The Code

// Client sends unique key
const res = await fetch('/api/payments', {
  method: 'POST',
  headers: {
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ amount: 9999, currency: 'USD' })
});

When You'll Hear This

"Always send an idempotency key with payment requests to prevent double charges." / "Stripe's API accepts Idempotency-Key headers to handle retries safely."