Open Navigation

Error Handling


Note that this guide is for the main Tray platform. If you are an Embedded customer please see the Error Handling guide for Tray Embedded edition

If any of the steps in your workflow encounter errors when communicating with third-party services (e.g. your Opsgenie API key doesn't have the correct access rights or you are trying to access a record that does not exist in Salesforce, Marketo etc.), you can choose how you would like to handle these errors.

Note: Error handling only concerns error messages returned by third-party services when operations are communicating with them. If misconfigured, some operations will fail in the Tray workflow builder before they communicate with the service. For example, if you are using the Slack Send message operation and have changed the channel drop-down to a jsonpath but mis-form your jsonpath (e.g. by entering instead of $ then the connector will not actually send a request to the Slack service API in order to receive a recognised error message.

There are 3 ways of dealing with errors:

  1. Continue - if the error is insignificant then you can continue the workflow as normal

  2. Manual - it is possible to create 'Success' and 'Error' branches coming from the connector step in question, so that you can set exactly what happens in the workflow should an error be encountered with this step. This works much the same as a boolean connector

  3. Stop workflow (default) - in this case the workflow is stopped and an error payload can be sent to an error handling workflow which you need to set up

Choosing the Error Handling method

For any connector step, you can find the Error Handling method drop-down by scrolling down to the very bottom of the operations panel:


The Continue workflow option

If you select the Continue option the workflow will continue on to the next step, but you will notice that the step in question has a blue alert symbol next to it:


Note that you should be careful about using the continue method as, if other steps are dependent on any output data from it, it could break your workflow.

The Manual option

If you choose Manual Alerting you will see a green success and red failure branch coming from your connector step. So you can then, for example, send an alerting email (this is of course a very simple example, and you could use the error branch to build a sophisticated alternative route for your workflow):


The above example shows how to compile a simple email (this could also be a message to a Slack channel or any other option you might want to implement) which makes use of the error message from the output of the errored step.

Accessing error messages

Looking at the debug output of an errored step shows you what fields are available:


Note: when referencing the error message from the step, it must be done in the format $.errors.<step-name>.message. The above example makes use of interpolated mode by inserting the error into the content of the email message with {$.errors.opsgenie-1.response.body.message}

This then picks up any API errors that might be generated and sends them in a composed email such as:


The Stop Workflow (Default) option

Errors can be sent to another workflow and that workflow is responsible for handling the alerting. One case for this would be to use the HTTP connector to pass on any errors to your monitoring system of choice.

Please note that you should not use this setup if you are a Tray Embedded customer. Go to our guide to Error Handling (Embedded) for Embedded-specific instructions on setting up an alerting workflow.

There are two steps to setting this up:

  1. Create an alerting workflow using the Alerting Trigger
  2. Configure your workflows to send their errors to your alerting workflow

You can use the same alerting workflow to handle the errors from multiple workflows. For example, you might set up your alerting workflow to send you an email with details of each error it receives. You can set all of your existing workflows to report their errors in this way.

Creating an alerting workflow

Create a new workflow and select the Alerting Trigger as its trigger.


This is a special kind of trigger that can accept alerting payloads from other workflows. Alerting payloads are in the following format:

workflow_uuidThe UUID of the workflow which sent the error
workflow_urlThe URL of the workflow which sent the error
workflow_titleThe title of the workflow which sent the error
step_nameThe name of the specific step which was the cause of the error. Note that the is not the user-configured name but the unique name given by Tray
step_log_urlThis URL can be used to go directly to the point in the logs at which this error occurred
connectorThe type of connector (and version) that caused the error
messageThe internal Tray-generated error message
createdA timestamp of when the error occurred



Your alerting workflow can make use of these fields to provide useful information for debugging. The payload includes the uuid, url, and title of the workflow which has errored as well as the specific step name and a link to the step in logs. This link to the logs is useful for debugging the cause of the error.

Workflows with an alerting trigger behave just like any other workflow. You can build any logic you like into your workflow to handle the incoming errors.

Configuring your workflow to send errors to your alerting workflow

Click on the cog in the top left corner of the builder. This will open the Workflow Settings panel. From here you can set the alerting workflow which will handle the errors from this workflow (you may need to refresh the page to see a just-created alerting workflow in the list). Note that only workflows with an Alerting Trigger will appear in this list.


Important notes

Errors are only sent to alerting workflows once all retries of a workflow have failed.

Multiple workflows can use the same Alerting Workflow but a workflow can't send its errors to more than one Alerting Workflow.

Video Tutorial

The following video provides a short tutorial on using alerting in practice:

Was this article helpful?