Handle errors

Use the Handle errors block to keep a pipeline running when a step inside it fails. Instead of stopping the whole pipeline at the first failure, you wrap the steps you want to watch and decide what happens next: run a set of recovery steps, or carry on without them.

Handle errors is a logic block, like a condition or a loop. You add it from the logic menu, then place steps, or other logic blocks, inside it.

When to use the handle errors block

By default, when any step in a pipeline fails, the pipeline stops and the remaining steps don't run. That's the right behavior most of the time—but not always. Sometimes a step is allowed to fail and you want the pipeline to continue. Other times a failure should trigger a follow-up, like a notification or a record in an error table.

The Handle errors block gives you that control. With it, you can:

• Catch a failure and route the pipeline to recovery steps—for example, send a message to Slack with the error details.

• React to success with a separate set of steps that run only when everything inside the block worked.

• Ignore a failure entirely, so an optional step can't stop the rest of the pipeline.

How the Handle errors block works

A Handle errors block has two parts:

• The monitored steps—the steps you place inside the block, between the Start monitoring and Stop monitoring markers. These are the steps whose failures the block watches for.

• The outcome paths—what runs after the monitored steps finish. In handle errors mode, the block creates two paths, On success and On error, and runs one of them based on the outcome.

When the block runs:

• If all monitored steps succeed, the On success path runs.

• If a monitored step fails with an error the block can catch, the remaining monitored steps are skipped and the On error path runs instead.

• After either path finishes, the pipeline continues at the next step after the block.

Which errors are caught

The Handle errors block catches errors that come from your data or your request—the kind a service reports when it rejects what the pipeline sent. For example: a required field is missing, a value is invalid, a record already exists, or a field doesn't exist. These are the errors that would normally stop the pipeline with a "step failed" message.

The block does not catch errors that aren't about your data. These keep stopping the pipeline, the same as before:

• Connection problems—the platform can't reach the service at all.

• Unexpected or internal errors—for example, the platform fails while reading the service's response.

Note:

Rate limits and heavy-traffic conditions are handled separately, by Pipelines' automatic retry. Instead of failing right away, the step is throttled and retried with a back-off. Only after all retries are exhausted does the error become terminal and stops the pipeline.

A few cases are worth keeping in mind:

• Authentication errors are caught and won't stop the pipeline, but Pipelines still counts each one. After enough consecutive failures, the connected account can be deauthorized, and pipelines that use it are suspended.

• An error inside a loop iteration doesn't stop the pipeline; an enclosing Handle errors block won't catch it either. To capture and act on errors, nest a Handle errors block inside the loop.

• A Stop step isn't a failure. A Stop step inside the monitored steps stops the pipeline normally, just as it would anywhere else. The block doesn't treat it as an error.

Add a Handle errors block

1. In the pipeline designer, add a new logic block and select Handle errors.

2. Place the steps you want to watch inside the block, between Start monitoring and Stop monitoring.

3. Leave the mode set to Handle errors. The block shows an On success path and an On error path.

4. Add the steps that should run when the monitored steps all succeed to the On success path.

5. Add the steps that should run when the monitored steps fail to the On error path.

You can add more than one Handle errors block to a pipeline.

Handle errors mode and ignore errors mode

You can choose what to do when errors occur:

• Handle errors—the block shows the On success and On error paths, and you define what happens in each case.

• Ignore errors—the block has no outcome paths. If a monitored step fails, the failure is swallowed: the remaining monitored steps are skipped and the pipeline continues with the first step after the block. Use this for an optional step that should never stop the pipeline when you don't need any follow-up logic.

Choose ignore errors instead of leaving the outcome paths empty. It keeps the pipeline simpler.

If you switch a block from handle errors to ignore errors, any steps on the On success and On error paths are deleted. The designer warns you first and lists the steps that will be removed, so you can cancel before anything is lost.

By default, the pipeline keeps going after the On error path runs. Once the path finishes, it resumes at the first step after the block.

If you want the pipeline to stop instead, add a Stop step as the last step on the On error path. The Stop step ends the run, just as it would anywhere else in a pipeline.

Example: notify a Slack channel when a record can't be created.

If your pipeline creates a record in Quickbase, and you want a Slack message whenever that fails:

1. Put the Create Record step inside a Handle errors block, set to handle errors mode.

2. On the On error path, add a Slack – Send message step.

3. In the Slack message, include the error details.

Now, if the record can't be created, the pipeline no longer just stops. It sends your Slack message, then continues.

Use the error details

When the On error path runs, the details of the failure are available under a global key named ERROR. You can reference these values in the mappings of your On error steps, the same way you reference any other step's output. In the reference dropdown, the source appears as Error from handle errors, or "Error from" followed by your block's name, if you renamed the block.

The ERROR object contains:

For example, to include the error message in a Slack notification, map the message field to {{ERROR.error_message}}.

Nesting Handle errors blocks

You can place a Handle errors block inside another within the monitored steps, or on the On success or On error path.

When blocks are nested, the innermost block gets the first chance to handle a failure. If it handles the error, the outer block never sees it. If it can't, the failure travels up to the next block out.

The ERROR object always describes the failure of its own block. If you nest blocks, each On error path sees the failure from its own monitored steps, never an outer block's failure.

Steps inside a nested Handle errors block can't be referenced from outside that block. This applies to every step in the nested block, the monitored steps and the steps on both the On success and On error paths.

Share data between the monitored steps and the outcome paths

Steps on the On success and On error paths can reference the monitored steps, so you can pass data from a monitored step into your follow-up logic.

Keep in mind that a monitored step may or may not have run, depending on where a failure happened:

• On the On success path, every monitored step ran successfully, so all of their data is available.

• On the On error path, the block ran because something failed, so there's no guarantee a given monitored step ran. If your On error logic relies on a specific monitored step's output, add a condition that checks the value is present, so a missing value can't cause a second failure.

Steps outside the Handle errors block can't reference anything inside it, not the monitored steps, and not the steps on the outcome paths. To use a monitored step's output later in the pipeline, add those steps to the On success path instead. On success runs only when every monitored step succeeded, so the data will be there.

Note:

The steps on the On success and On error paths are ordinary steps. If one of them fails, it stops the pipeline like any other failure. The Handle errors block doesn't protect its own outcome paths. To guard a step on an outcome path, wrap it in its own nested Handle errors block.

Conditions and loops inside a block

Conditions work normally inside a Handle errors block. If a step inside a condition's branch fails, the block catches it and runs the On error path.

A failure inside a loop iteration is contained by the loop itself and does not travel out to an enclosing Handle errors block. So if you put a loop inside a block's monitored steps and an iteration fails, the block won't run its On error path. It treats the loop as successful and runs On success.

The designer shows a warning on a loop placed inside a Handle errors block: When steps inside a loop fail, they aren't handled by the Handle errors block.

If you need to catch failures that happen inside a loop, put a Handle errors block inside the loop body instead of around the loop. Then each iteration's failure is handled where it happens.

Handle errors results in the Activity log

Every time a Handle errors block runs, the pipeline records an entry in the Activity log showing the block's mode and how it ended, with or without an error.

In the Activity log filters, Handle errors blocks appear under the Logic filter, together with conditions and loops.

When an error is caught, the entry shows the same failure details that are available in the ERROR object: which step failed, its channel and type, and the error message, so you can explore exactly what the block caught.

Limitations

• Triggers can't go inside a block. A trigger step can't be one of the monitored steps. A Handle errors block can be the very first step of a pipeline only when the pipeline isn't trigger-based.

• Only errors caused by your data or request are handled. Rate limits, connection problems, and unexpected internal errors still stop the pipeline.

• Loops don't propagate errors. A failure inside a loop isn't caught by an enclosing Handle errors block. To catch it, put a Handle errors block inside the loop body.

• Some steps handle their own errors. Steps such as Import to Quickbase, Copy Records, and the HTTP channel have their own error handling. You can place them inside a Handle errors block as part of a larger group you want to monitor, but the block doesn't change how they behave.

• Failure emails are still sent. The usual failure email is still sent when a step fails, whether the error was handled or ignored.