Skip to main content
All CollectionsBest Practice GuidesGeneral
What error codes can I expect from Merge and how do I handle them?
What error codes can I expect from Merge and how do I handle them?

An overview of error handling and recommended retry logic

Updated over a week ago

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

Did this answer your question?