Retries are part of the interface
A timeout does not tell you whether a request failed. Build the next attempt with that uncertainty in mind.
A client sends a request, waits, and times out. From the client’s point of view, nothing happened. On the server, the operation may already have finished. That gap is where a harmless retry can become a duplicate order, another email, or a second background job.
Separate delivery from outcome
A successful network exchange and a successful business operation are different facts. If a connection closes before the response arrives, the client has an unknown outcome. Treating that as a definite failure makes the next action harder to reason about.
For operations that change state, give the client a way to identify the intended operation. An idempotency key lets repeated delivery refer to one piece of work rather than creating a new piece of work each time.
Make the contract explicit
A useful contract says how long a key is retained, what happens when the same key is used with different input, and whether an operation can still be running when a retry arrives. These are part of the interface, not merely storage details.
Keep the result associated with the operation’s identity. If the first attempt completed, the retry should return the corresponding result. If it is still running, return a clear pending response rather than starting another copy.
Wait with a reason
Retries should have a limit and a delay. Backoff spreads load over time; jitter prevents many clients from returning together. A server-provided retry interval should take precedence when it is part of the API contract.
Do not retry every error. Invalid input needs a correction, authorization failures need a different decision, and a permanent rejection will not improve after another second.
A retry policy is incomplete until it explains when to stop.
Test the uncertain case
Test a response that disappears after the operation commits. Test two deliveries that arrive together. Test a retry after the retention window. These cases tell you more about reliability than sending the same successful request several times in sequence.
The goal is not to guarantee that every request succeeds. It is to ensure that another attempt has a predictable meaning.