Recover from a failed step

What On Error does

Every node has an On Error policy that decides what happens when that step fails after its retries are exhausted. You set it in the node inspector, under the On Error section, on any node that does work and can fail (app actions, HTTP, code, transforms, AI nodes, and the data nodes).

There are three modes:

On Error is the inline, same-run reaction to a failure. It runs at the step itself, so a node can fail and the run keeps moving. That is different from the run-level error handler trigger, which fires only after the whole run has already died.

Continue past a failure

Pick Continue when a step is non-essential and you would rather skip it than abort the run. A failed enrichment lookup, an optional notification, a best-effort write: continue keeps the run alive and hands the next step an error-shaped output instead of a result.

1. Open the node inspector

   Select the node that might fail and open its configuration panel.

2. Set On Error to Continue

   In the On Error section, choose Continue. The run will now proceed down the node's normal connection even when the step fails.

3. Add a fallback output (optional)

   Continue reveals a Fallback output field. Enter a static JSON object to substitute as the step's data when it fails, so downstream mappings see a stable shape instead of an empty object. Leave it empty to pass {}.

When the step fails, its output is:

{
  "data": {
    /* your fallback output, or {} */
  },
  "meta": {
    "errorHandled": "continue",
    "error": {
      "code": "HTTP_502",
      "message": "Bad gateway",
      "retryable": true,
      "failedStepId": "s_http_3",
      "failedNodeId": "node_http"
    }
  }
}

The error detail always rides on meta.error, so a recovered failure is never silently lost. The next step can read it and branch on it.

Route a failure to a recovery branch

Pick Route to recovery branch when a failure needs its own handling: log it, repair the payload, send it to a dead-letter step, or retry through a different path. Route gives the node a second output handle you wire to a separate branch.

1. Set On Error to Route to recovery branch

   In the On Error section, choose Route to recovery branch. The node gains a second output handle on the canvas, labeled On error with a dashed connector, so the recovery path is visually distinct from the success path.

2. Wire the error handle to your recovery steps

   Drag from the On error handle to the first step of your recovery branch. Until you do, the inspector shows a reminder, and publishing fails with a validation error rather than silently falling back to Stop.

3. Filter by error code (optional)

   Add one or more error codes to route only those failures down the branch. Codes outside the list fall through to Stop. Leave the list empty to route every error.

In the recovery branch, the failing step's input is forwarded as data so you can inspect or repair the original payload, and the structured error is available on the $error expression binding:

$error.code
$error.message
$error.item

See Expressions for how to read $error in your recovery steps.

Which item failed

When the failing step runs inside a Loop, the error carries the exact item that failed and the loop iteration index:

{
  "code": "HTTP_429",
  "message": "Too many requests",
  "failedStepId": "s_http_3",
  "failedNodeId": "node_http",
  "iterationIndex": 4,
  "item": { "id": "cus_8842", "email": "ada@example.com" }
}

So a Loop over a thousand records can route the four that failed to a cleanup branch, with full context on each, while the rest of the batch completes.

Test it before you publish

On Error resolves at the step itself, which means a single-node test run exercises it the same way a live run does. Run the node in test mode with a payload that makes it fail, and you see the same meta.error block and meta.errorHandled stamp the production run produces. You do not have to publish and wait for a real failure to know your error handling works.

See a recovered step in run history

A node that errored but was handled inline shows a Recovered badge in run history, tagged with the mode that handled it (Recovered · Continue or Recovered · Route). The step status stays completed, so a recovered failure is easy to tell apart from a failed step that stopped the run.

Choose the right tier

On Error is the middle of three ways to react to a failure. Pick by how much power you need and how fast you need it:

The key boundary: Continue and Route keep the run alive and successful, so no run-level error workflow fires. Only Stop (or an unhandled error inside a recovery branch) lets the failure reach the run-level error handler. If you set a node to Continue, your error workflow will not trigger for that node — that is the point.

Lock On Error to Stop for a workspace

A workspace admin can pin On Error to Stop at the workspace level. When that floor is set, every node's Continue and Route options are disabled in the inspector, with a tooltip explaining the policy. No node can loosen it. Use this for regulated or compliance-sensitive workflows where silently swallowing a failure is not acceptable.

Next steps

• Write expressions to read $error in a recovery branch.
• Route and repeat steps to build the branch a failure routes into.
• Read a failed run to see recovered steps in run history.