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

Handle	Direction	Description
input	Input	Receives from the node being watched
success	Output	Taken when the preceding node succeeded
error	Output	Taken when the preceding node failed

Configuration

Field	Type	Description
catch_error_codes	array	Optionally restrict which error codes to catch (empty = catch all)
log_error	boolean	If true, adds caught error details to the output as _caught_error
clear_error	boolean	If true, removes the error from the execution context after catching

Catchable Error Codes

Code	Description
VALIDATION_ERROR	Data failed validation
NODE_TIMEOUT	Node exceeded time limit
NETWORK_ERROR	Network or HTTP request failure
AUTH_ERROR	Credential authentication failed
PERMISSION_ERROR	Permission denied
NOT_FOUND	A queried resource was not found
RATE_LIMIT	External API rate limit hit
CONFIG_ERROR	Node configuration error
EXECUTION_ERROR	Generic execution failure
UNKNOWN_ERROR	Unclassified error

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]

💾 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