- Get started
- Build
- HTTP Request
- How connector nodes work
- Create a connection
- Sales and customer relationships
- Customer support and help desk
- Messaging and meetings
- Email
- Marketing
- Social media
- Files, documents, and e-signature
- Projects, collaboration, and code
- People and recruiting
- Finance and commerce
- AI models and agents
- Speech, vision, and language
- Data and location
- Cloud, identity, and security
- Deploy and run
- Examples
- Reference
Handle errors
Route failed nodes to an error path, return the error details, retry temporary failures, and end the workflow cleanly on unrecoverable errors.
What you build
A workflow that routes a failing node to a separate path, records the failure with useful context, retries temporary failures where that makes sense, and ends cleanly when the error is unrecoverable. The result is a pattern that fits into any existing workflow.
Before you start
- An existing workflow with at least one node that can fail and has an Error handling tab, for example an HTTP Request or an Extract node.
Nodes used
- HTTP Request: the node that can fail in this example.
- Script: returns the error details.
- Terminate: ends the workflow on unrecoverable errors.
Steps
With a coding agent set up, you can skip the manual steps. Ask it:
Add error handling to the HTTP Request node in this Maestro Automate workflow: connect its error path to a Script node that returns the error message, retry temporary failures, and end the run with a Terminate node when the error can't be recovered.
Add error handling to the HTTP Request node in this Maestro Automate workflow: connect its error path to a Script node that returns the error message, retry temporary failures, and end the run with a Terminate node when the error can't be recovered.
Then open the workflow on the canvas, check it against the steps below, and test it. Set up your coding agent describes the setup.
1. Connect the node's error handle
By default, a failed node stops the entire workflow. To handle the failure instead:
-
Open the workflow on the canvas and select the node that can fail.
-
Open the Error handling tab and turn on Enable error handling. An Error handle appears below the main output handle.
-
Select the + on the Error handle, search for Script, and select it.
This creates an error path. When the node fails, the run follows this path instead of stopping the workflow. A node without an Error handle does not support error handling, and a failure there stops the workflow and appears in the Incidents tab.
2. Return the error details
In the Script node on the error path, read the error object at $vars.<node>.error and return the details:
const error = $vars.httpRequest1.error;
return {
message: "Error raised: " + error.message,
code: error.code,
status: error.status
};
const error = $vars.httpRequest1.error;
return {
message: "Error raised: " + error.message,
code: error.code,
status: error.status
};
The Script node's output appears in the execution trace, so the error details are visible when you inspect the run. The error object is only populated on the error path. The Error handling page lists the full set of error fields.
3. Retry transient failures (optional)
If the failure is likely to be temporary, such as a network interruption or a rate limit, retrying before giving up helps. The HTTP Request node has built-in retries: setting Retry count on its Advanced tab makes it re-attempt the request that many times before triggering the error handle. Only the final failure routes to the error path.
Retry only operations that can safely run more than once. Retrying a node with side effects, such as writing data or sending a message, can create duplicates.
4. Terminate if unrecoverable
On the error path, after the Script node, add a Terminate node. To return the failure description, select Add output variable on the node and give it a value that includes the error, for example $vars.httpRequest1.error.message.
The workflow ends at the Terminate node, and the run is listed in Monitor runs.
5. Test and debug
To trigger the error path intentionally:
- Temporarily set the URL in the HTTP Request node to an invalid value (for example,
https://this-will-fail.example.com). - Select Run Debug (▶) in the bottom toolbar of the canvas and verify that the execution trace follows the error path.
- Restore the correct URL.
In the trace, select the Script node and check its output for the error message.
Result
The workflow routes failures to the error path, returns the error details, optionally retries temporary failures, and ends cleanly with a descriptive failure status. An invalid URL in the HTTP Request node confirms that the error path works.
Extend this workflow
- Send an alert on failure: on the error path, before the Terminate node, add an HTTP Request or connector node to notify a Slack channel or create a ServiceNow incident.
- Continue instead of terminating: if the step is non-critical, have the error path set a fallback value and rejoin the main path instead of terminating.
- Apply this pattern widely: the Error handling page describes more patterns, such as returning error details and continuing, fallback values, and escalation.
Next steps
- Deploy a workflow: make the workflow run without you.
- Guides: more workflows to build.
- Community: share what you built, or ask other builders for help.