docs / Reference / Definition language
Error handling
The `on_error` rules, and what a rule can do with the error it matched.
Error rule
One entry of a task’s on_error.
| Field | Type | Required | Description |
|---|---|---|---|
case | string | Extra condition on the matched error, checked alongside code. A false case falls to the next rule. | |
code | string[] | Error code patterns. ’%’ is the only wildcard; every other character is literal. Empty = catch-all. | |
goto | string | Task to route to when retries are exhausted. ‘$task-id’ or ‘end’. Omit to fail the instance. | |
not_reached | boolean | Assert this code means the remote was never reached, so an only_once task may retry it. | |
panic | Fault | Terminate as ‘failed’ with this code and message — a defect. Nothing can catch a panic. | |
raise | Fault | Terminate as ‘raised’ with this code and message — a condition a parent can catch. | |
retry | Retry | Retry policy applied before the rule routes. Omit for no retries. |
Retry
The value of a rule’s retry.
integer
Shorthand for ‘retries’, on the default backoff curve (1s, doubling, capped at 5m).
object
The long form: retry count plus any part of the backoff curve. Every slot takes a $: expression.
| Field | Type | Required | Description |
|---|---|---|---|
delay | string | number | Wait before the first retry: ”30s”, a number of milliseconds, or a $: expression. Defaults to 1s. | |
factor | number | string | Multiplier applied to the wait after each attempt. 1 keeps it constant. Defaults to 2. | |
max_delay | string | number | Ceiling the growing wait is clamped to. Defaults to 5m, or to ‘delay’ when that is longer. | |
retries | integer | string | Number of retries before following goto or failing. 0 = no retries. |
Fault
The value of a rule’s raise or panic.
| Field | Type | Required | Description |
|---|---|---|---|
code | string | yes | Error code, lower_snake_case with no dots. A literal — never an expression. |
message | string | yes | Human-readable message. A template: ${ } renders when the clause fires. |
data | Shape | Structured payload this fault carries, evaluated when the clause fires. Lands on error.data. |