A timeout tells your application that it didn't receive a result in time. It doesn't establish that the receiving service rejected the operation. That distinction matters when an integration creates a contact, opens a support request or performs another consequential write.
This is an illustrative design discussion, not a report about a customer incident or a tested implementation for a specific vendor.
Start with a business operation reference
Give the intended action a stable reference before attempting delivery. Keep that reference when the browser refreshes or the worker restarts. A newly generated reference on every retry makes it harder to recognize that two requests represent the same intended action.
Separate what you know
The operation can be prepared but not attempted, conclusively rejected, confirmed by the receiving service, or uncertain after an attempted write. An HTTP timeout belongs in that last category until further evidence resolves it. A generic failed label loses the distinction that tells an operator whether another write is safe.
Use the provider's actual recovery capability
Some providers offer idempotency keys. Others expose a reference lookup or an operation-status endpoint. Their scope, retention and concurrency behavior differ. Verify those details for the endpoint you use. A disabled submit button prevents some repeated clicks, but it doesn't establish exactly-once processing across retries, workers and provider failures.
If supported read-only checks find the result, save that evidence against the original operation. If the provider can't establish what happened, stop for review. Don't convert uncertainty into an automatic retry simply because retry code is easy to write.
Make the operator path part of acceptance
For a labelled fixture, simulate a lost response after a successful write. Refresh the interface, open the original operation and check the result without resubmitting it. Inspect the destination record and the stored operation state. Then test a genuine rejection separately. Those are different recovery cases.
Useful operational evidence includes timestamps, operation references, provider references and redacted error categories. Agree access and retention. Private enquiry text, credentials and unnecessary customer details don't belong in ordinary logs.
Define the boundary honestly
This pattern improves traceability and helps control duplicate actions. It doesn't provide a universal exactly-once guarantee. The strongest claim you can make depends on the provider's documented behavior and the concurrency and lost-response tests you've actually run.
Disclosure and optional reference
The author works with StackEndBox. Our public integration project checklist expands the buyer-facing questions around field ownership, sync direction and operator recovery: https://www.stackendbox.com/blog/api-integration-project-checklist
This contribution was prepared with AI assistance. Its examples are illustrative, with no customer data or claimed production benchmark.
Top comments (0)