An integration can fail in an uncomfortable way: the caller does not receive a response, but the receiving system may already have completed the operation. A timeout describes what the caller observed. It does not always describe what happened to the business transaction.
That distinction matters for payments, insurance requests, loan applications, and any workflow where repeating an action can create a duplicate or leave two systems disagreeing.
Model the business state, not just the HTTP response
A useful transaction model distinguishes between a request that has not been sent, one that is awaiting confirmation, one that is confirmed, and one that has failed conclusively. Include a way to represent an uncertain outcome rather than forcing every timeout into a final failure state.
The states, names, and transitions should match the provider’s contract and the business process. For example, an illustrative status sequence might be Created → Submitted → Pending confirmation → Confirmed. That example is a design aid, not a description of any particular employer’s implementation.
Make repeated requests safe
Agree on an idempotency contract with the receiving service. A stable request identifier can allow the receiver to recognise a repeated business operation and return a consistent result. Generating a new identifier on every attempt defeats that protection.
Define what the identifier represents, how long it remains valid, how concurrent duplicates are handled, and what happens if a caller reuses it with a different payload. The protection must be enforced by the service performing the action; adding a header alone does not make an operation safe.
Give retries a budget
Retrying can help with transient failures, but an unlimited retry loop can amplify an outage. Set bounded attempts, suitable delays, and an overall time budget. Use the provider’s documented guidance for retryable errors and respect throttling signals.
Microsoft’s Retry pattern guidance highlights both the value of retries for temporary faults and the risks of repeated non-idempotent operations. A missing response can follow a successful action, so a blind retry may repeat the side effect.
Permanent validation or authorisation errors generally need correction, not repetition. For an uncertain write, a status query, reconciliation process, or provider-supported duplicate check may be more useful than another create request. A circuit breaker can also stop persistent dependency failures from consuming the entire application.
Plan how the systems will agree again
Design reconciliation as part of the integration. Identify the source of truth, the records to compare, the frequency of checks, the exception owner, and the evidence needed to resolve a mismatch. Include an escalation route for records that cannot be corrected automatically.
If the provider uses webhooks, verify their authenticity using the documented mechanism. Expect delayed or duplicated notifications, and avoid relying on arrival order unless the contract guarantees it. Record processed events so that redelivery does not repeat a completed business action.
Make support possible without exposing data
- Use correlation identifiers across the user request, internal processing, and provider interaction.
- Record state transitions and timestamps so an operator can reconstruct the sequence.
- Avoid logging secrets or unnecessary customer information.
- Show users a clear pending state and an appropriate next step when confirmation is delayed.
- Provide a controlled support process for investigation and correction.
Test what happens between the happy paths
Test a response lost after the provider commits, a repeated request, a duplicate webhook, a long provider outage, and a restart during processing. Check the final business state, not only the status code or the presence of an exception.
Dependable integration comes from a clear answer to four questions: what do we know, what remains uncertain, how do we recover, and who owns the exception? Those answers turn an API connection into an operable business capability.
Further reading: Microsoft Azure Architecture Center — Retry pattern.