Request Status Codes

You can tell if your request was successful by checking the status code when receiving an API response. If a response comes back unsuccessful, you can use the error type and error message to figure out what has gone wrong and do some rudimentary debugging (before contacting support). A successful request will be returned with status code 200.

Before reaching out to support with an error, please be aware that 99% of all reported errors are, in fact, user errors. Therefore, please carefully check your code before contacting zipcodestack support.

Status codes

Here is a list of the different categories of status codes returned by the zipcodestack.com API. Use these to understand if a request was successful.

Name
200
Type
Description
A 200 status code indicates a successful response. Note that on most endpoints missing or invalid request parameters currently also return status code 200 with an error-shaped body — see Validation errors below.
Name
401
Type
Description
A 401 status code indicates that your API key is missing or invalid. A missing key returns the message No API key found in request (error code missing_api_key); an invalid key returns Unauthorized (error code invalid_api_key).
Name
403
Type
Description
A 403 status code indicates that you are not allowed to use this endpoint with your API key — either the key belongs to a different everapi product (error code key_not_allowed_for_product), or the request's referrer is not on the API key's referrer whitelist (error code referrer_not_allowed).
Name
404
Type
Description
A 404 status code indicates that a requested endpoint does not exist, or that a supplied postal code could not be found: /v1/match returns the error under a codes key (e.g. 99999 could not be found in our database.), while /v1/radius returns it under an error key with postalcode ... not found wording.
Name
405
Type
Description
A 405 status code indicates an HTTP method the endpoint does not take (error code method_not_allowed); the Allow header names those it does. A HEAD request answers 405 on every billed endpoint, without running it and without being billed; /v1/status and the other free endpoints answer HEAD like GET.
Name
422
Type
Description
A 422 status code indicates that request parameters failed validation on /v1/validate, /v1/autocomplete or /v1/reverse — see Validation errors below. /v1/radius, /v1/polygon, /v1/code/city and /v1/code/state also answer 422, with the same body, for a page that is no whole number from 1 (on radius and polygon such a limit reads as 10000). So do /v1/radius, /v1/distance and /v1/match for a parameter sent as a list where one value is expected (e.g. code[]=1&code[]=2), a unit other than km, mi or miles, a radius that is no number or negative, or a distance that is no number, and /v1/polygon for coordinates that are not a list of [longitude, latitude] pairs within ±180 and ±90, whose edges cross each other, of more than 1,000 coordinate pairs or in a body over 128 KiB, and for a polygon whose search takes longer than 5 seconds (split it into smaller polygons). Every endpoint answers 422 for a parameter that is no valid UTF-8 (except the code lists codes and compare, where such a code is left unmatched).
Name
429
Type
Description
A 429 status code indicates that you have hit your rate limit or your monthly limit. For more requests please upgrade your plan.
Name
500
Type
Description
A 500 status code indicates an internal server error - let us know: support@zipcodestack.com
Name
503
Type
Description
A 503 status code indicates that a /v1/radius search took longer than its time limit, e.g. a wide radius in a dense country. It is not billed; a smaller radius or limit answers, or try again later.

Validation Errors

The newer endpoints /v1/validate, /v1/autocomplete and /v1/reverse answer invalid parameters with HTTP status code 422 and the standard error body:

{
    "message": "Validation error",
    "errors": {
        "country": ["The country field is required."]
    },
    "info": "For more information, see documentation: https://zipcodestack.com/docs/status-codes#_422"
}

On all other endpoints, a missing or invalid request parameter currently returns HTTP status code 200 (except the 422 cases listed above) with an error-shaped body rather than a 4xx status. Do not rely on the status code alone to detect these errors — if the response body contains parameter error keys instead of the expected query/results structure, treat the request as failed.

The error body maps each offending parameter to a message, and most validation errors also include an info link to the documentation (the /v1/search response to more than 100 postal codes currently omits it):

{
    "country": "required",
    "info": "For more information, see documentation: https://zipcodestack.com/docs/status-codes#_200"
}

Typical validation error messages include:

Name
required
Type
Description
A required parameter is missing, e.g. {"codes": "required"}.
Name
you can only submit 100 postalcodes at once
Type
Description
More than 100 postal codes were submitted via the codes (search, match) or compare (distance) parameter.
Name
has to be 500 km or less
Type
Description
The radius parameter exceeds the maximum of 500.
Name
limit has to be an integer
Type
Description
The limit parameter is not an integer.