Error Handling

HTTP Errors (4xx/5xx)

As with any web service, our API will return 4xx and 5xx level errors when appropriate. Always check the status code to ensure the request was successfully received and successfully handled.

A 4xx level error code indicates that something is wrong with the request. Our recommendation is to double check the request for any typos.

If you receive a 413 Entity Too Large error when creating a job, you may need to break the data into smaller chunks or use a Remote URL to submit the data.

A 5xx level error code indicates that something went wrong on our end. Our recommendation is to attempt the request again and check our API's status. If the request is still failing let us know at [email protected].

API Errors

All 2xx level responses will contain a status property. This property will indicate whether the requested operation was successfully completed or if an error was encountered.

When an error does occur a message property will be included with a detailed message about why it failed. These error messages will be returned with a 200 level status code.

{
  "status":"general_failure",
  "message":"Missing required parameter 'key'",
  "execution_time":5
}

Status Code	Description
`success`	The request was successful
`general_failure`	Something went wrong with the request; check the `message` property for further details
`auth_failure`	The request couldn't be authenticated; ensure your API key has been typed correctly and that you're using a V4 API key (See authentication for more info)
`temp_unavail`	An internal error has occurred; typically this indicates a partial service interruption
`throttle_triggered`	The request was rejected due to rate limiting; try again shortly
`bad_referrer`	The referrer for this request is not trusted

Language Specific Examples

<?php

try {
    // Call wrapper method here
} catch (\NeverBounce\Errors\AuthException $e) {
    // The API credentials used are bad, have you reset them recently?
} catch (\NeverBounce\Errors\BadReferrerException $e) {
    // The script is being used from an unauthorized source, you may need to
    // adjust your app's settings to allow it to be used from here
} catch (\NeverBounce\Errors\ThrottleException $e) {
    // Too many requests in a short amount of time, try again shortly or adjust
    // your rate limit settings for this application in the dashboard
} catch (\NeverBounce\Errors\HttpClientException $e) {
    // An error occurred processing the request, something may be wrong with
    // the Curl PHP extension or your network
} catch (\NeverBounce\Errors\GeneralException $e) {
    // A non recoverable API error occurred check the message for details
} catch (Exception $e) {
    // An error occurred unrelated to the API
}

// The Node.JS wrapper does not throw exceptions. Instead it utilizes 
// asynchronous promises to handle successful and erroneous responses.
// 
// A rejected promise will contain the error object as the argument. The error
// object itself will contain both a `type` and `message`. See the example below.

client.account.info().then(
    resp => console.log(resp), // Successful response fulfilled
    err => { // Erroneous response rejected
        switch(err.type) {
            case 'AuthError':
                // The API credentials used are bad, have you reset them recently?
                break;
            case 'BadReferrerException':
                // The script is being used from an unauthorized source, you may need to
                // adjust your app's settings to allow it to be used from here
                break;
            case 'ThrottleError':
                // Too many requests in a short amount of time, try again shortly or adjust
                // your rate limit settings for this application in the dashboard
                break;
            case 'GeneralError':
                // A non recoverable API error occurred check the message for details
                break;
            default:
                // Other non specific errors
                break;
        }
    }
);

try:
    # Call wrapper method here
except neverbounce_sdk.AuthFailure as e:
    # The API credentials are bade, have you reset them recently?
except neverbounce_sdk.BadReferrer as e:
    # The script is being used from an unauthorized source, you may need to
    # adjust your app's settings to allow it to be used from here
except neverbounce_sdk.ThrottleTriggered as e:
    # Too many requests in a short amount of time, try again shortly or adjust
    # your rate limit settings for this application in the dashboard
except neverbounce_sdk.GeneralException as e:
    # A non recoverable API error occurred check the message for details

resp, err := // call client method
if err != nil {
	// Attempt to cast the error into a neverbounce.Error to
	// handle-able error objects
	if nbError, ok := err.(*neverbounce.Error); ok {
		// Check Error types
		if nbError.Type == neverbounce.ErrorTypeAuthFailure {
			// The API credentials used are bad, have you reset them recently?
		} else if (nbError.Type == neverbounce.ErrorTypeBadReferrer) {
			// The script is being used from an unauthorized source, you may need to
			// adjust your app's settings to allow it to be used from here
		} else if (nbError.Type == neverbounce.ErrorTypeThrottleTriggered) {
			// Too many requests in a short amount of time, try again shortly or adjust
			// your rate limit settings for this application in the dashboard
		} else {
			// A non recoverable API error occurred check the message for details
		}
	} else {
		// Handle non NeverBounce errors
	}
}

begin
  client = NeverBounce::API::Client.new(...)
  resp = # Call client method
rescue => e
  # Log the error with full backtrace.
end

try
{
  // Call SDK method (use await)
  // e.g: var resp = await sdk.Account.Info();
}
catch (AuthException e)
{
  // The API credentials used are bad, have you reset them recently?
}
catch (BadReferrerException e)
{
  // The script is being used from an unauthorized source, you may need to
  // adjust your app's settings to allow it to be used from here
}
catch (ThrottleException e)
{
  // Too many requests in a short amount of time, try again shortly or adjust
  // your rate limit settings for this application in the dashboard
}
catch (GeneralException e)
{
  // A non recoverable API error occurred check the message for details
}
catch (Exception e)
{
  // An error occurred unrelated to the API
}

Cross-Origin Request Blocked (CORS Errors)

Errors pertaining to a Cross-Origin Request or a missing Access-Control-Allow-Origin header indicate that our standard API is being called from within a web browser. Doing so is not supported, as it exposes private API credentials in your client-side application. These private API credentials are able to be used to access any data you've uploaded to your account, so they should never be used in a public context like a web browser. Instead you should create a server side component to make the request to our API to conceal your private API credentials.

If you're looking for a quick and easy way to add email verification to your website or web-application (Angular, React, Vue, jQuery, or other Javascript library) you can use our Javascript Widget.