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 an internal server error - let us know: support@numlookupapi.com

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.

  • Name
    numbers
    Type
    Description

    On the batch endpoint the request is rejected with a 422 and an errors object when numbers is missing, empty or longer than 100 entries ("A batch can contain at most 100 numbers."). Unreadable single numbers do not fail the batch; they get "error": "invalid_number" in their own entry.