API Error Codes

API Error Codes

We understand that things don’t always go well when making your first API call, especially when it’s your first time integrating with our API. Let’s look at the most common status codes that indicate an error response with a brief explanation:

Be advised - In June 2023, ZeroBounce added a security measure called API Shield. The API Shield is a dynamic security feature and may be enabled and disabled throughout the day based on traffic patterns, ongoing attacks, maintenance, and other factors. If the API Shield is enabled, you may sometimes receive a 403 Forbidden response, while when disabled, the API error codes below will be displayed. Please consider all these error codes as exceptions.

429 - Too Many Requests when such error occurs it is advised to consider throttling the requests as you’ve hit the rate limits. Also please refer to the API Rates Limit section in the documentation.

400 - Bad Requests in most cases this suggests that there is an error in your API request, please recheck the documentation.

404 - Not Found the most common error code, it simply means that the endpoint you are trying to reach does not exist on the API server, best will be to check for typos or recheck the documentation.

405 - Method Not Allowed this suggest you are trying to access a HTTP resource using an unsupported REST method (example, you are trying to do a GET on a POST endpoint), please recheck the documentation.

500 - Internal Server Error while highly unlikely, the error suggest a platform issue and you’ll need to contact support.

520 or 524 - Unexpected unknown error While highly unlikely, this suggests a transport error that may occur for a number of different reasons. We constantly monitor and address any and all 520/524 occurrences with our transit providers, and will be available to assist you. Please retry at your earliest convenience or contact our support team for more information.