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.
Choose retention from business risk
A short cache may stop immediate duplicates but fail when a delayed queue redelivers. A permanent record may create unnecessary storage or privacy burden. Document key expiry and what happens if a key is reused after that boundary.
Put side effects behind the idempotent boundary
If rule evaluation triggers a message or database write, use a transactional outbox or equivalent pattern so the decision and pending event are committed together. Consumers still need their own deduplication because downstream delivery is often at least once.
Return decision provenance
Include the decision ID, status, rule artifact version, timestamp, and whether the response was replayed. Do not regenerate a result under a newer rule version for a duplicate key unless the caller explicitly requests a new business operation.
Test the failure modes, not only the happy path
Cover concurrent duplicates, payload mismatch, worker crash after commit, delayed redelivery, key expiry, and downstream retry. Observe duplicate attempts and mismatches as signals; they frequently reveal client bugs or abuse.
DecisionManager publishes patterns for event-driven and governed decision services. Idempotency works when it is a durable business contract, not an in-memory cache attached to one server.
Top comments (0)