Asynchronous callbacks: retries, idempotency, and evidence

Separate acceptance from result

In an asynchronous operation, the initial response confirms that a request was accepted for processing. It does not confirm that data already exists or that the query succeeded. The interface must communicate that difference and retain the request identifier.

This decoupling handles work with different durations without holding a connection open. It also requires explicit states: accepted, processing, completed, failed, or expired, depending on what the contract actually exposes.

Use a stable identity end to end

The request ID should travel from acceptance through the callback, logs, and operational intervention. Do not replace it with a timestamp or screen identifier; either can repeat or disappear when a component changes.

For batches, add an item-level identity. This lets you resume one part without repeating completed work and explain exactly which element needs attention.

Design retries that do not duplicate effects

A callback may arrive more than once because the sender cannot know whether the receiver persisted the first delivery. The receiver must recognise the same operation, store the result once, and answer later deliveries consistently.

The idempotency key must be bound to the correct business identity. If it is calculated from mutable data or the current time, retries can look like new operations.

• Validate authenticity before processing.
• Persist result and identity atomically.
• Return success for a duplicate already applied.
• Separate transient failure from permanent rejection.

Turn delivery into evidence

A useful trace connects the client request, internal work, every callback attempt, and receiver confirmation. Logs do not need sensitive data; safe technical identities, states, timing, and error codes are enough.

Alert on ageing queues, retry rates, and destinations that reject delivery. The right observability lets teams act before a technical delay becomes a data discrepancy for the customer.