Idempotency keys can also be known as request ids [1] or correlation ids. They can help in situations where you have a distributed system with an API provider

Idempotency keys can also be known as request ids [1] or correlation ids. They can help in situations where you have a distributed system with an API provider and an API client and some operation needs to be performed "once-and-only-once". Since the network can drop requests or responses, the client must retry requests that appear to have failed, but perhaps might have succeeded. Since the client might retry an operation that actually succeeded and send multiple messages for the same operation, either the operation must be inherently idempotent, or if not, the API provider must be able to de-dupe requests. Adding an idempotency key is a way to allow the API provider to detect and de-dupe requests. It requires work and collaboration on the part of the API client and the API provider. The API client must generate a unique idempotency key for each logically different operation it attempts to execute, and it must retry requests for operations that appear to have failed using that fixed idempotency key. If the operation is not inherently idempotent, the API provider needs to implement some way of de-duping repeated requests - perhaps storing requests in a durable cache for N hours/days keyed by the idempotency key. One industry where these "once-and-only-once" execution guarantees are useful is banking. Customers expect their payments to be executed exactly once, so their accounts are debited once and not zero times or 2+ times. There's an interesting infoq podcast from 2018 with Jason Maude of Starling Bank [2] talking about how they design their bank systems for "once-and-only-once" execution. From memory, Jason decomposes the responsibilities as: API clients are responsible for ensuring operations execute at least once. API providers are responsible for ensuring operations execute at most once. [1] see e.g. google's API design guidelines for request identification: https://google.aip.dev/155 https://google.aip.dev/155 [2] https://www.infoq.com/podcasts/cloud-based-banking-startup-java/ https://www.infoq.com/podcasts/cloud-based-banking-startup-j...