Idempotency keys: the API integration bug that costs companies the most money

Of all the integration bugs we've debugged for clients, one category shows up more than any other, and quietly costs the most money: duplicate writes. Double-charged customers. Two shipping labels for one order. Duplicate welcome emails. Almost every time, the root cause is the same — a network retry with no idempotency key.

Why retries cause duplicates

Networks fail. A request can succeed on the server but time out before the client gets the response. When that happens, most integration tools automatically retry — which is correct behavior for a failed request, but catastrophic for a request that actually succeeded the first time. Without a way to tell the server "this is the same request as before," it just runs the action again.

What an idempotency key actually does

An idempotency key is a unique identifier your integration generates once per logical operation (not per HTTP attempt) and sends with the request. The receiving API stores that key against the result of the first successful call. If the same key arrives again — because of a retry — the API returns the original result instead of executing the action twice.

POST /v1/charges
Idempotency-Key: order_48213_charge_attempt
{
  "amount": 4200,
  "currency": "usd",
  "customer": "cus_9F3nK2"
}

Most modern payment and messaging APIs (Stripe, Twilio, many others) support this natively via a header. If you're building a custom webhook handler yourself, you need to implement the same pattern manually — store a key against every write, and check for it before executing.

Implementing it in your own workflows

In Make or n8n, this usually means: generate a deterministic key from the source event (like the source system's own record ID, not a random UUID), store executed keys in a data store module, and check that store before making the downstream write. If the key's already there, skip the write and return the stored result.

A real example we fixed

A DTC brand client was seeing roughly 40 duplicate order confirmations per week from their Shopify → fulfillment integration. The webhook itself was fine — the fulfillment API's rate limiter was occasionally timing out the response, triggering an automatic retry with a fresh request, no key attached. Adding an idempotency key tied to the Shopify order ID eliminated it completely.

The results

• Zero duplicate fulfillment requests over the following 3 months
• No more manual refund processing for accidental double-charges
• Support tickets related to "why did I get two confirmation emails" dropped to zero

If your integrations retry on failure — and they should — make sure they can't accidentally repeat success. Get in touch if you want us to audit yours.