Idempotency for External Calls

Idempotency means applying the same operation multiple times has the same effect as applying it once. This matters when calling external services where retries due to timeouts, network hiccups, or errors must not cause duplicate side effects like charging a customer twice. Implement idempotency by attaching a unique client-generated key to each request and storing the result keyed by that id.

When the server receives a request, it checks if the idempotency key already has a recorded result. If yes, it returns the cached result instead of re-processing. If no, it executes the operation, records the outcome, and responds. This works even if the client retries the request multiple times; only the first execution triggers actual work.

Idempotency keys must be stable and hard to guess—commonly UUIDs or monotonic counters. Avoid using request body alone, since bodies may change in transit or be modified during retries. Design APIs to be safe and idempotent by default for non-transactional operations, especially create or update endpoints that modify state.