Errors & retries
Runtime is in development. These guides explain design intent; they are not a released API or installation reference. Read the release policy →
Classify the failure before retrying
Section titled “Classify the failure before retrying”An invalid request, a temporary transport issue, and an uncertain remote write require different handling. A broad “retry every exception” rule can multiply load and duplicate changes.
No automatic retry behavior or reliability guarantee is claimed for Runtime by this page.
Ask whether the outcome is known
Section titled “Ask whether the outcome is known”A connection failure before sending may leave no remote change. A timeout after sending can leave the result unknown. If the remote side committed but the response was lost, repeating the request may repeat the write.
Idempotency means repeated work has the intended equivalent effect. It requires an agreed identity, scope, storage lifetime, and duplicate-response contract. A random request identifier on its own does not provide idempotency.
Bound the retry policy
Section titled “Bound the retry policy”| Decision | Why it matters |
|---|---|
| Retryable outcomes | Avoid retrying input or authorization failures blindly |
| Attempt and elapsed-time limits | Keep work within the caller’s budget |
| Delay and jitter | Reduce synchronized bursts against a recovering service |
| Cancellation | Stop unnecessary local work while tracking uncertain remote effects |
| Terminal reporting | Preserve useful context without exposing credentials |
Backoff does not replace capacity limits. If retries are scheduled, account for queued work and its memory or persistence needs.
Test uncertainty explicitly
Section titled “Test uncertainty explicitly”Simulate “remote commit, lost response,” duplicate requests, exhausted retry budgets, and cancellation during a delay. Observe side effects as well as returned errors. Record any required compensating action in the integration contract.
See testing for a scenario-based approach.