Error handling

Handling error messages based on different response codes is critical to API development. Here’s a general approach to handling various HTTP response codes coming back from Merge effectively.

Categorize response codes

HTTP error codes can be categorized into different classes. Only some are used by Merge.

3xx: Redirection messages (not returned by Merge)
4xx: Client errors
5xx: Server errors

Define error handling logic

Here are the types of errors returned by Merge and guidance on each:

4xx: Client errors

Code	Issue	Description	Retry	Troubleshooting Tips
400	Bad Request	Malformed request- data is not present in the 3rd Party System and/or the 3rd party system does not support the request.	No	Check if the 3rd party system has the data you want to pull or push to. Check our docs to see what endpoints we support for each integration.
401	Unauthorized	Unauthorized: authorization is either missing or misconfigured.	No	If this is a test account, make sure you are using the Account Token stored in the bottom right of their Linked Account page. If this is a production account, the account token are available in the dashboard and should be stored in your database.
404	URL Not Found	The resource was not found with the given identifier- the request was entered incorrectly.	No	Check our docs on how to format our requests to the Merge API.
404	URL Not Found	The resource was not found with the given identifier- the data does not exist.	No	Check if the data is present within the 3rd party system.
404	URL Not Found	The resource was not found with the given identifier- the integration does not support that endpoint.	No	Check our docs to see what common models our integrations support.
404	URL Not Found	The resource was not found with the given identifier- the subdomain was entered incorrectly.	No	Check for a valid subdomain. If it is accurate, contact support.
429	Too Many Requests	The Merge Organization has reached a rate limit for the requested linked account, preventing any more requests from going through.	Yes	Retry using the logic explained in the Automatic Retry section below.

5xx: Server errors

Code	Issue	Description	Retry	Troubleshooting Tips
500	Internal Server Error	Merge is experiencing a service interruption.	Yes	Retry using the logic explained in the Automatic Retry section below.
502/503	Service Interruption	Check the 3rd party integration status page, they are likely experiencing an outage.	Yes	Retry using the logic explained in the Automatic Retry section below.

Automatic retry

It's generally best practice to have pre-defined retry logic when encountering specific error codes. Below is guidance on what logic we recommend setting for each response code you get back from Merge.

Automatic retry logic

Use the retry logic outlined below to ensure that transient issues do not cause immediate failures, improving the resilience of your integration.

Code	Issue	Description	Retry Logic
429	Too Many Requests	The Merge Organization has reached a rate limit for the requested linked account, preventing any more requests from going through.	Retry the request after an initial 1 minute delay, increasing the delay exponentially with each retry (aka "exponential backoff")
500	Internal Server Error	Merge is experiencing a service interruption.	Retry the request after an initial 10-30s delay, increasing the delay exponentially with each retry (aka "exponential backoff")
502/503	Service Interruption	Check the 3rd party integration status page, they are likely experiencing an outage.	Retry the request after an initial 10-30s delay, increasing the delay exponentially with each retry (aka "exponential backoff")

What is "exponential backoff"?

An exponential backoff algorithm reduces the rate of API requests in response to an error code. For example, if an API request hits a 5xx error, it might try again 1 second later, then if it fails again, 2 seconds later, then 4 seconds, etc. Each time, the pause and subsequent attempt are multiplied by a fixed amount (in this case, 2).

Merge's Error Codes within Logs