Timeouts and Cancellation in Blockchain API Clients
Set request deadlines, propagate cancellation and distinguish an unknown outcome from a confirmed failure when an API connection ends unexpectedly.
Overview
When translating these concepts into an integration, keep the scope described by the wallet history api with the result. The examples in wallet transaction history and smart contract event logs show how the same distinction affects neighbouring data questions.
A timeout tells the caller that the desired response did not arrive within a budget. It does not always prove that remote work stopped or that a submitted operation failed.
Use an end-to-end budget
Separate connection, response and total-operation deadlines where the client supports them. Propagate cancellation to underlying reads and waiting retries. A sequence of individually bounded requests can still exceed a useful overall deadline unless the operation tracks its remaining time. Keep cancellation distinct from a valid empty response.
Worked example: a timed-out submission
A service accepts an operation but the response connection closes before the client receives its identifier. Automatically repeating a non-idempotent submission can duplicate work. A read-only query may be safely retried under a bounded policy, while a state-changing operation needs an idempotency or lookup contract to resolve the uncertain outcome.
Test interruptions deliberately
Include a server that never responds, a partial body, cancellation during parsing and a caller that disconnects. Do not display timed-out data as zero activity. Record safe diagnostic codes without credentials or complete sensitive payloads. A retry should be chosen from operation semantics, not merely from the fact that an exception occurred.
A practical acceptance test
Make a read hang, send a partial body and cancel during a retry wait. Assert that the whole operation respects its deadline and releases resources. In a separate non-idempotent submission fixture, lose the response after acceptance. The client must preserve unknown outcome and use its recovery contract rather than blindly submit the operation again.
Questions about the topic
Frequently asked questions
Does a timeout prove remote failure?
No. The remote outcome can be unknown.
Can many short request timeouts still create a long operation?
Yes. Use an overall deadline as well.
Standards & technical documentation