Ipregistry uses conventional HTTP response codes to indicate the success or failure of an API request.

In general, codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g. a required parameter was omitted or an invalid value was passed). Codes in the 5xx range indicate an error with Ipregistry's servers (these are rare).

To ease debugging, quickly identify issues but also to facilitate programmatic handling, all errors include an Ipregistry error code, a message that describes the problem, and a resolution field that gives guidance about how to fix the error. Below is an example in JSON:

message: "You have not supplied an API key.",
resolution: "Add your API key as a query parameter:"

Here is an exhaustive list of all error codes:

Error CodeHTTP StatusDescription
BAD_REQUEST400You specified an invalid request payload, for instance with our bulk endpoint. Check examples at
DISABLED_API_KEY451Your API key is disabled. This may be caused by your account email that has not been verified after multiple recalls or if malicious activities are detected.
FORBIDDEN_IP403IP filtering is enabled for the API key in use and the user request is from an IP that you did not whitelist.
FORBIDDEN_ORIGIN403Origin filtering is enabled for the API key in use and the request origin is from an origin that does not match the ones you allowed.
FORBIDDEN_IP_ORIGIN403IP and origin filtering are enabled for the API key in use and the user request is not matching what you allowed.
INTERNAL500An unexpected error has occurred on Ipregistry servers. Please check your request and retry again.
INSUFFICIENT_CREDITS402You need to buy credits to continue using the service (we send up to 3 email alerts before you run out of credits).
INVALID_API_KEY403Your API key is invalid. Make sure you are using the right key or check its value for a typo.
INVALID_FILTER_SYNTAX400The filter pattern you entered to select a subset of fields is invalid. Decompose your filter into smaller parts and test them incrementally.
INVALID_IP_ADDRESS400The IP address that was searched is not a valid IPv4 or IPv6 address.
MISSING_API_KEY401You did not specify an API key. Add your API key as a request parameter:
PRIVATE_IP_ADDRESS400The IP address that was searched is a reserved address (loopback, link-local, multicast, private, site-local or wildcard IP address). Such IP addresses do not make sense in a geolocation context.
TOO_MANY_IPS400You made a batch request with too many IP addresses. Batch requests must not contain more than 256 IP addresses. Input less IP addresses.
TOO_MANY_REQUESTS429Rate limiting was enabled for the API key in use and too many requests were made for the window you configured. Decrease your invocation rate or change your settings from the Ipregistry dashboard.
TOO_MANY_USER_AGENTS429You have specified too many user agents with the batch endpoint. Batch requests must not contain more than 256 user agents. Input fewer user agents.