You hit "Submit Order" and the network drops mid-request. Did the charge go through? Should you retry? Without idempotency keys, you're gambling — and your users are the ones losing money.
Idempotency is the property that making the same request multiple times has the same effect as making it once. Idempotency keys are how you enforce that at the API layer, and every API that processes payments, sends emails, or creates resources should implement them.
How Idempotency Keys Work
The client generates a unique key (usually a UUID) and attaches it to the request as a header. The server stores the key alongside the result. If the same key arrives again — from a retry after a timeout, a double-click, or a network flap — the server returns the cached result instead of re-processing.
POST /v1/charges
