Try/Catch shape

To view this content in our official product documentation, click here.

Introduction

Using the try/catch shape, you can build your own path to handle process flow sync exceptions elegantly.

Place a try/catch shape before key steps in your flow, then configure its settings to determine behaviour when exceptions are found. Once this is done, the shape is added to the canvas with two routes - one for try and one for catch:

 

For the try route, build your flow in the usual way to achieve the required result. For the catch route, define a flow that should be followed for exceptions. For example, you might add exceptions to a cache (so they can be processed subsequently) and then notify specified contacts that exceptions have occurred.

The notify shape can be very powerful when used with the **try/catch** shape. Keep in mind that you can include meta, flow, and payload variables to define notification messages. For example:\ \ \ \ Here:

• the variable resolves with the value of the team flow variable (defined in process flow settings)
• the [[payload.ref]] variable resolves with the value of the ref field from the incoming payload
• the [[meta.error_message]] variable resolves with the error message associated with the exception
   

The `[[meta.error_message]]` variable is a standard variable that can be used to access error/exception messages.

When the process flow runs, data flows down the try route and ideally completes without exceptions. However, if an exception is found, the associated payload is removed and sent along the catch route.

{% hint style="warning" %} You can add one try/catch shape per process flow {% endhint %}

A single incoming payload for any process flow shape should not exceed 500MB.

We recommend processing multiple, smaller payloads rather than one single payload (1000 x 0.5MB payloads are more efficient than 1 x 500MB payload!).

For payloads up to 500MB, consider adding a flow control shape to batch data into multiple, smaller payloads. Payloads exceeding 500MB should be batched at source.

Need to know

• You can add one try/catch shape per process flow
• If a connector needs to retry authentication, the retry is NOT caught (i.e. it's not sent into the catch route). If re-authentication is successful the flow continues as normal (i.e. along the try route), otherwise the process flow fails.

Caught exceptions

As noted above, if an exception is found it gets removed (as a failed payload) and sent along the defined catch route. For example, if a try/catch shape receives 20 payloads and finds 4 exceptions, then 4 failed payloads are sent along the catch route.

Failed payloads can be found on the failed payloads tab in run logs - for example:

 

Adding & configuring a try/catch shape

To add and configure a new try/catch shape, follow the steps below.

Step 1\ In your process flow, add the try/catch shape in the usual way:

 

You can add one try/catch shape per process flow. It's up to you where you place this in your flow, but it's generally a good idea to add it at the very start to ensure that all steps are checked.

Step 2\ Access settings for the newly placed shape:

 

Step 3\ Choose the action to take if an exception is encountered:

 

Available options are summarised below:

Action	Flow behaviour
Succeed as partial success	The flow completes and, where possible, data is synced. Failed payloads for exceptions are removed and are available from run logs. The flow is logged with a status of partial success.
Fail flow	The flow completes and, where possible, data is synced. Failed payloads for exceptions are removed and are available from run logs. The flow is logged with a status of failure. In this case, the flow is marked as a failure (and will show as such in run logs) but it's important to note that this does not cause the process flow to stop - any valid payloads continue through the flow. It's likely that you would only use this option instead of succeed as partial success if logging any failed payloads as a general flow failure is important from a reporting/metrics perspective.
Fail flow & retry	Use this option with care. When the process flow is retried, all data is processed again. If you have any doubt as to whether duplicate records will be handled correctly, we advise using a different action and manage exceptions separately (for example, add exceptions to a cache and process from there). A retry will only happen if the process flow is enabled and deployed, and is NOT triggered manually. The flow completes and, where possible, data is synced. Failed payloads for exceptions are removed and are available from run logs. The flow is logged with a status of retried. The flow is retried with ALL data. The flow is retried ONCE only.

Step 4\ Save settings to return to the canvas and build your try and catch routes as required.

Related pages

• Run logs - failed payloads
• Notify shape