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

Retry policy

Most responses with a status code other than 200 is considered an error, and the retry policy will apply. This is how each endpoint/scenario will behave:

• Authorization URL: User will see your URL's error screen
• Subscribe to custom trigger: User will see an error message on monday.com
• Unsubscribe to custom trigger: User will see an error message on monday.com
• Call a custom action's Run URL: We will retry the request for 30 minutes unless the app returns a 4xx status code or severity code
• Remote options URL: User will see Could not load fields error message
• Remote field definitions in dynamic mapping: User will see Could not load fields error message

📘

Note on webhook integration

The policies above only apply to endpoints in custom monday apps. Requests through the Webhook integration will not retry.