Define the business result

Consider a hypothetical store: the payment provider confirms a payment, but the response never reaches the store. Retrying may create another operation; giving up may leave the order unpaid internally. Before choosing a library, define what counts as payment, where its state lives and which identifier connects it to the order.

Make repeat processing deliberate

For operations that create something, use an idempotency key when the provider supports it. Preserve that key across retries of the same business request. Incoming events need their own processing record: an event identifier and protection against applying the same order change again. These mechanisms solve different problems.

Separate receipt from expensive work

A webhook should be authenticated and durably recorded first. File delivery, email and report generation can then run through a queue. If email delivery temporarily fails, retry the email rather than recreating the payment and order. Retry policy depends on the operation and the API’s documented limits.

Keep a reconciliation path

An error log can locate a failure, but recovery also needs a link between the local record and the provider’s object. Plan how to reconcile stuck operations and safely retry them manually. Test lost responses, duplicate and out-of-order events, and provider downtime alongside the successful flow.

Sources