Catch

Type key: catch
Group: Flow Control
Category: flow
Tier: CORE

The Catch node intercepts errors produced by the immediately preceding node and routes execution to one of two branches: success (no error was raised) or error (an error was caught). It enables graceful error handling and recovery without terminating the entire workflow.

Handles

Configuration

Catchable Error Codes

Leave the list empty to catch all error types.

Behavior

When the engine executes the Catch node:

1. It checks the centralized execution error log (errors recorded by the engine during the run).
2. If there are no errors in the context: data flows through the success handle unchanged.
3. If there is at least one error in the context:
   • The Catch node considers only the last recorded error.
   • If catch_error_codes is configured, only errors matching those codes are caught.
   • Caught errors flow through the error handle with enriched error context (_caught_error).
   • If the last error does not match the filter list, Catch itself returns failure (Error not caught (code filter)).

Error Context on the error Branch

When log_error: true, the error output adds a _caught_error key to the output:

{
  "_caught_error": {
    "code": "NETWORK_ERROR",
    "message": "HTTP request failed with status 503",
    "node_id": "uuid-of-the-failed-node",
    "severity": "error",
    "timestamp": "2025-03-16T10:00:00Z"
  },
  ...original input fields...
}

This allows downstream nodes on the error branch to log, notify, or react based on the specific error type and message.

When to use each output handle

• Use the error handle for recovery logic: notify, fallback HTTP call, write an error record, return an HTTP error response, etc.
• Use the success handle to continue the normal path when nothing failed.

A canonical pattern is placing Catch immediately after a “risky” node:

[Send Webhook / HTTP Request / DB write]
          │
          ▼
       [Catch]
       │     │
   success  error
       │     │
       │     ▼
       │  [System Notification / Fallback / HTTP Response]
       ▼
   [Continue normal flow...]

Common pitfall: filtering out EXECUTION_ERROR

Many node failures are recorded as EXECUTION_ERROR. If you enable code filtering and forget to include EXECUTION_ERROR, Catch will not route to error and will instead fail with Error not caught (code filter).

Example: HTTP Request with Fallback

[HTTP Request: Primary API]
          │
          ▼
       [Catch]
       │     │
   success  error
       │     │
       │     ▼
       │  [HTTP Request: Fallback API]
       │     │
       └─────┘
          ▼
      [Merge]
          │
       [Transform]

::: info 💾 Try this example Download the workflow JSON — open an empty workflow and import the file. :::

Example: Send Error Alert

[Data Model]
     │
     ▼
  [Catch]
  │     │
success  error
  │       │
  │       ▼
  │   [Send Mail: alert@team.com]
  │   Subject: Workflow error: {{error.message}}
  │
[Transform]

Notes

• The Catch node does not modify data on the success branch — it's a transparent pass-through when no error occurs
• Catch nodes can be chained: place a Catch after every risky node for fine-grained error handling
• Without a Catch node, any node failure terminates the entire execution with status failed
• Combine with the Set Variable node on the error branch to store error information for later use in the workflow