Retries are normal in distributed systems. A caller may time out after the server commits a decision, a queue may redeliver a message, or a webhook sender may repeat an event. A decision API that treats every request as new can double-charge, duplicate actions, or record conflicting outcomes.
Give each business operation a stable key
The idempotency key should identify the logical business request, not a network attempt. Store it with a normalized request fingerprint, processing state, outcome, rule version, and response. If the same key arrives with a different payload, reject it rather than returning an unrelated prior result.
Handle concurrent duplicates atomically
Two workers can receive the same key before either writes a result. Use a unique constraint, transaction, or compare-and-set operation so only one execution owns the request. Other attempts should wait, return an in-progress response, or read the completed outcome according to the API contract.
