Idempotency key

DEFINITION

An idempotency key is a client-generated unique identifier (usually a UUID) sent in a request header (Idempotency-Key) on every state-changing POST, PUT, or DELETE. Payment APIs (Stripe, Adyen, SimplePay, PayPal) use it to guarantee that if the same key arrives twice (because the network dropped, the client retried, the load balancer retried), the operation runs exactly once and the second response is the cached first response. Without it, a client retrying after a 30-second timeout charges the customer 100 thousand forints twice. Retry logic must not exist without an idempotency key on the payment, order placement, email send, and webhook delivery layers. Worth doing on your own API too: put a Postgres unique index on the key, and de-duplicate either at the call boundary or on the event queue.