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 numlookupapi support.

Status codes

Here is a list of the different categories of status codes returned by the numlookupapi.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 a well-formed but unrecognised phone number also returns a 200 — check the valid field of the response, see the validation endpoint.

  • Name
    401
    Type
    Description

    A 401 status code indicates that your request was not authenticated: the 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) — see Authentication.

  • Name
    403
    Type
    Description

    A 403 status code indicates that your request was refused: either the API key belongs to a different everapi product (error code key_not_allowed_for_product), or the request came from a referrer that is not on your API key's whitelist (error code referrer_not_allowed).

  • Name
    404
    Type
    Description

    A 404 status code indicates that a requested endpoint does not exist.

  • Name
    422
    Type
    Description

    A validation error has occurred, please check the list of validation errors.

  • 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 a internal server error - let us know: [email protected]

Validation Errors

  • Name
    invalid_number
    Type
    Description

    The phone number is empty or could not be parsed. Provide the number either including its country prefix (e.g. +14158586273) or without the prefix together with the country_code parameter.

  • Name
    invalid_country_code
    Type
    Description

    The selected country_code is invalid. Should be an ISO 3166-1 alpha-2 country code (e.g. US), used to prepend the correct country prefix to the phone number.