This guide is designed to stand on its own as an educational reference. It separates technical concepts, commercial outcomes and policy considerations so readers can reason about the system rather than memorize terminology.
The duplicate problem
Networks fail in ambiguous ways. A client can send a request, lose the response and retry. A provider can send the same callback more than once. A user can refresh after an event has already been recorded. If every repeated message creates value, duplicate rewards are inevitable.
Choose the logical operation carefully
An idempotency key should identify the reward decision or fulfilment intent, not the individual HTTP attempt. If retries generate new keys, the protection disappears. Keys also need an appropriate retention period so an old request cannot be replayed after the system forgets it.
Forward-only state transitions
A state model might move from created to eligible, submitted and then succeeded or failed. Once a terminal state is reached, later contradictory events should be handled explicitly rather than silently rewinding the transaction. Forward-only rules make audit histories easier to reason about.
Verify the evidence source
A success message is only useful if the system trusts its origin. Provider callbacks should be authenticated according to provider documentation, and internal reward events should be tied to the user journey that created them.
Reconciliation is the backup control
Even good real-time logic can miss events. Periodic reconciliation compares local state with provider state and surfaces discrepancies for retry or investigation. Idempotency prevents duplicates; reconciliation prevents silent loss.
Design for retries before production
Test timeouts before provider acknowledgement, after acknowledgement but before response, and during callback delivery. A system that only works when every request succeeds immediately is not production-ready, even if the happy-path demo looks perfect.