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. |
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. |
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).