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 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 Invalid authentication credentials (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
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: [email protected]

Validation Errors

A missing or invalid request parameter currently returns HTTP status code 200 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
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.