HTTP and API contracts
API retries: identity, deadlines and uncertain outcomes
By the BackendDrills editorial team · Published and checked October 6, 2026 · 7-minute read
Before you start: HTTP requests and durable writes. Find this reading in a study path →
A timeout tells the caller that it lacks a response within its budget. It does not establish whether the server committed the business operation. Give retries an operation identity, and give uncertain outcomes a way to be resolved.
The response disappears after acceptance
In an original practice example, a booking service stores a reservation, but the network drops its response. The client wants to retry. If the service treats every POST as a new booking, the same intent can produce two reservations. If it refuses all retries, the customer cannot learn what happened.
| Request situation | Contract to define |
|---|---|
| Same identity, same intent | Return or locate the recorded outcome. |
| Same identity, changed payload | Reject the mismatch under an explicit rule. |
| Identity currently executing | Provide a bounded wait or documented status response. |
| Identity no longer retained | State the retry horizon and recovery method. |
Scope the identity to the authenticated owner and operation. Persist the decision atomically with the durable local effect where possible. If an external provider performs the effect, its identity and lookup contract become part of recovery; a local “started” row is not proof of provider success.
Read the method contract carefully
HTTP defines idempotence in terms of the intended server effect of repeated requests. That does not guarantee identical responses, free retries or safe behavior for an arbitrary POST endpoint. Document your business contract rather than deriving it from the button label or a generic client library.
Budget the whole call
Draw caller, service and downstream attempts on one timeline. Allocate connection setup, execution and any retry inside the remaining caller budget. Repeated retries at several layers can amplify load precisely when the dependency is struggling. Assign one retry owner, bound attempts and choose which failures are eligible.
Practice the ambiguous window
- Submit one synthetic operation and record its identity.
- In a controlled fixture, lose the response after the durable effect commits.
- Retry with the same identity; inspect stored effects, not only the status code.
- Repeat with a changed payload and a second authenticated owner.
- Write what the client displays while the outcome is uncertain and how it resumes safely.
Your final artifact is a contract table covering success, definitive rejection, execution in progress and unknown completion. Use a status lookup or reconciliation path to turn uncertainty into evidence before asking the customer to start a new operation.
Check the underlying behavior
Original illustrative examples, prepared with AI assistance and checked against the linked primary documentation. No customer incident or vendor endorsement is claimed. Our editorial approach.
Practice the next decision
Try a complete free backend drill: inspect evidence, make three decisions and review the reasoning. No account or card required.
Try a free incident drill →Selected practice from the study paths
- The double-click becomes a double charge. · Full edition drill
- A timeout outlives the caller's deadline · Full edition drill
- Circuit breaker errors erase an uncertain result — recovery exercise · Full edition drill
Free readings need no account. Full edition drills require verified access; opening a paid link does not expose its answers.