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). 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:

Here is an exhaustive list of all error codes:

Error CodeHTTP StatusResolution
BAD_REQUEST400This error is raised when you specify an invalid request payload, for instance with our bulk endpoint. Check examples on or drop us a line at [email protected]
DISABLED_API_KEY451API keys are disabled if your account email has not been verified after multiple recalls or if malicious activities are detected. Please check your email or contact us at [email protected]
FORBIDDEN_IP403You can manage the whitelist from the Ipregistry dashboard:
FORBIDDEN_ORIGIN403You can manage the whitelist from the Ipregistry dashboard:
FORBIDDEN_IP_ORIGIN403Filtering is enabled for this API key but your request origin 'X' and your IP address 'Y' are not allowed. You can manage whitelisted request origins and IP addresses from the Ipregistry dashboard:
INTERNAL500An unexpected error has occurred. Please check your request and retry again.
INVALID_API_KEY403Check your API key for a typo or contact us at [email protected]
INVALID_FILTER_SYNTAX400Decompose your filter into smaller parts and test them incrementally.
INVALID_IP_ADDRESS400Enter a valid IPv4 or IPv6 address.
MISSING_API_KEY401Add your API key as a request parameter:
PRIVATE_IP_ADDRESS400Enter a public and valid IPv4 or IPv6 address.
TOO_MANY_IPS400Batch requests must not contain more than 256 IP addresses. Input fewer IP addresses.
TOO_MANY_REQUESTS429Decrease your invocation rate and retry after Y seconds. This error may only occur when you have enabled throttling for your API key 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. Your request contains X entries. Input less user agents.