Merge’s API provides tools that allow you to easily troubleshoot any issues with POST requests to Merge.
This consists of:
View the full list of possible errors and warnings in Writes Errors and Warnings Reference.
The warnings field contains details on issues that don’t stop the request from being successful.
The errors field contains details on issues that cause the request to fail.
Warnings in POST responses notify you about issues with the request that did not prevent the Common Model instance from being created.
For example, if the request contains an unrecognized field, we will ignore the field and notify you with a warning in the response.
For a list of possible errors and warnings returned by Merge’s API’s POST endpoints, check out the Warnings and Errors Reference.
Errors in POST responses notify you about issues with the request that prevented the Common Model instance from being created.
For example, if the request was missing a required field, then we will not create the Common Model instance and return an error response instead.
It’s generally best practice to have pre-defined retry logic when encountering specific error codes (429 or 5XX). Merge does not recommend retrying for other error codes. In the provided POST request example using our Node SDK, the retry logic handles errors based on HTTP status codes with an exponential backoff strategy.
If the request encounters a 429 Too Many Requests error, the logic waits for 60 seconds before retrying. For server errors (status codes 500-599), the code retries up to a maximum of 3 attempts, with each retry delay doubling (exponentially increasing) from an initial 5-second delay. If the maximum retries are reached or if an error falls outside these categories, the error is thrown. This ensures that transient issues like rate limits or server outages are gracefully handled with retries, while persistent issues are promptly reported.
Tip: Use the Idempotency-Key header to avoid creating duplicate records.
Logs of requests made from Merge to third-party platforms are available for transparency.
Debug Mode makes it easy to retrieve the logs for requests made from Merge to a third-party’s API as a result of a POST request to Merge.
This is most useful for cases where detail beyond the standard errors and warnings from Merge is helpful to troubleshoot, for example:
PROVIDER_ERROR)ERROR)To use Debug Mode, include is_debug_mode=true as a query parameter in the POST request.
In Debug Mode, the response includes the logs field, which is an array of log objects containing detail on outbound requests made to the end user’s API provider during the request.
Each log in the response will contain the following properties:
log_summary properties