CORE GUIDE
Timeout ambiguity
A timeout proves that a timely response was not observed; it does not prove that the remote operation failed.
Mental model
A timeout is a communication observation, not a conclusion about the remote side effect.
Why it matters
Distributed systems can lose responses after successful work, continue processing after the caller gives up, or fail before reaching the server. If an agent collapses all of those cases into FAILED, a seemingly reasonable retry can duplicate money movement, messages or other irreversible effects.
01
Three states behind one timeout
The request may have failed before execution, succeeded while the response was lost, or still be running. Safe handling therefore needs stable operation identity, idempotency when supported, and a reconciliation path that can query authoritative remote state before a new side effect is issued.
02
Example: the duplicate refund
A refund call times out. The agent labels it failed and retries with a new operation identity. Both calls eventually settle, refunding twice. Modeling the first result as UNKNOWN and reconciling by the original operation ID prevents the second side effect.
Common failure modes
- Mapping every timeout directly to FAILED.
- Generating a new operation identity on each retry.
- Reporting definitive failure before reconciliation is possible.
Engineering heuristics
- Represent ambiguous outcomes explicitly as UNKNOWN or PENDING.
- Keep the same idempotency key across retries of one intent.
- Provide an authoritative reconciliation path for costly side effects.
Takeaways
- 01Missing response is not confirmed remote failure.
- 02Retries become safer when one intent has one stable identity.
- 03Unknown is a legitimate runtime state and should be modeled explicitly.
Related concepts from the Knowledge Graph
These relationships come from the canonical graph, not a separate Guide taxonomy.