When building custom integrations, you should handle errors in a way that ensures a good user experience. Displaying descriptive errors when integrations fail makes troubleshooting issues easier for you and your users. Our framework provides two ways to categorize and communicate errors in your workflow blocks:

• Severity codes
• HTTP status codes

Severity codes

Severity codes let your user know what error occurred and the action required to fix it. We support two types of severity codes:

• 4000: indicates an error of medium severity and will result in a failed automation run
• 6000: indicates an error of high severity and will result in a disabled automation

You must send values in the 400 and 500 range to trigger these errors.

When to use severity codes

The difference between medium and high severity is whether or not the next run of your automation can succeed.

Let's say an automation should send an email based on a column value. An invalid value (such as a wrong email address) is a medium severity error. In this case, the automation is configured correctly and can succeed if the user fixes the email address. You can send an error message to prompt the user to change the email.

If the automation should move an item to a group and this group has been deleted since the creation of the automation, it should be categorized as a high severity error since the automation will always fail. The automation should be disabled, and the error should encourage the user to select a different group.

To implement severity errors, you must send any codes in the 400 and 500 range (4XX-5XX) with the following in the body:

{
"severityCode" : 4000,
"notificationErrorTitle" : "This is the notification title of of 4000",
"notificationErrorDescription" : "This is the notification description of 4000",
"runtimeErrorDescription" : "This is the activity log description of 4000"
}

{
"severityCode" : 6000,
"notificationErrorTitle" : "This is the notification title of 6000",
"notificationErrorDescription" : "This is the notification description of 6000",
"runtimeErrorDescription" : "This is the activity log description of 6000",
"disableErrorDescription" : "This is the disable message of 6000"
}

HTTP status codes

If you want to communicate failures without severity codes, you can send one of the following status codes in the response. We will then share it with the user based on our internal communication rules via the Activity Log.

• 401 - UNAUTHORIZED

• 402 - PAYMENT_REQUIRED

• 403 - FORBIDDEN

• 404 - NOT_FOUND

• 410 - GONE

• 422 - UNPROCESSABLE_ENTITY

Examples

Users will see the errors in three ways: in the Activity Log, as a notification, or as an error on the Board Automations page. Note that notifications or disabling of automations are only triggered if you implement severity codes.

Error description in the Activity Log

Notification to the Automation creator

Disabled automation with an error message

📘

Join our developer community!

We've created a community specifically for our devs where you can search through previous topics to find solutions, ask new questions, hear about new features and updates, and learn tips and tricks from other devs. Come join in on the fun! 😎