Error Codes
Learn more about error codes and how to resolve them.
Geolocated.io's API communicates the outcome of your requests using standard HTTP response codes. These codes are designed to inform you immediately about the success or failure of your API call.
- 2xx Codes signify successful requests. For example, a 200 OK response indicates the operation was successful, and the requested data is included in the response payload.
- 4xx Codes highlight errors caused by the request sent from the client side. These errors can stem from various issues, such as incomplete or incorrect data provided in the request. Here are common scenarios:
- A 400 Bad Request error may indicate a missing required parameter.
- A 404 Not Found error suggests that the requested API endpoint does not exist.
- 5xx Codes indicate problems on the server side, meaning the issue lies with Geolocated.io's infrastructure. While these occurrences are uncommon, they are not impossible. A 500 Internal Server Error, for instance, signals a broad server-side issue that needs addressing by our team.
In addition to the HTTP response codes, our APIs provide specific error codes within the response body to offer clearer insights into the nature of the issue encountered. Each error response follows a consistent structure, making it easier to parse and handle programmatically. The response body typically includes an error code and an optional human-readable error message. This approach allows you to quickly identify the root cause of an error and take the necessary steps to address it. Below is the JSON format outlining the structure of a typical error response. The following is a comprehensive list of potential error codes you may encounter, complete with detailed information for each.
The following is a comprehensive list of potential error codes you may encounter, complete with detailed information for each.
| Status | Error Code | Description |
|---|---|---|
| 400 | MalformedIpAddress | The IP address provided is not in a valid IPv4 or IPv6 format. Ensure the IP address adheres to standard formatting. |
| 400 | MalformedRequestPayload | The request payload does not adhere to the required format as specified in the API contract. For example, this error occurs when the batch request is not formatted as the expected JSON array. |
| 400 | TooManyIpAddresses | The batch request exceeds the allowed limit of 25 IP addresses. Please reduce the number of IPs in the request and try again. |
| 401 | ApiKeyRequired | The required api-key query parameter is absent in the request. Include this parameter with a valid API key for authentication. |
| 401 | UnrecognizedApiKey | The provided api key does not match any existing user account. Check the API key for any inaccuracies or consult the account dashboard. |
| 403 | SubscriptionExpired | The subscription to Geolocated.io has expired. Renewal or purchase of a new subscription is required for continued service access. |
| 403 | OriginNotAllowed | The origin of the preflight request is not part of the approved CORS domain list. Ensure the request is being made from an authorized domain or update the domain list if necessary. |
| 403 | RestrictedFeatureAccess | This endpoint or feature is not available under your current subscription plan. To access it, consider upgrading your subscription or reviewing the features included in your existing plan. |
| 404 | NoSuchApiExists | The requested API endpoint is either invalid or does not exist. Verify the endpoint's path and check the documentation for available endpoints. |
| 429 | RateLimitExceeded | The request rate limit for your current subscription level has been exceeded. Please wait before making additional requests or consider upgrading to a plan with a higher or unlimited request quota. |
| 429 | DailyLimitExceeded | The daily request quota for your current subscription level has been reached. Please wait until the limit resets or consider upgrading to a plan with a higher or unlimited daily quota. |
| 500 | UnexpectedServerError | Suggests a temporary problem within our server infrastructure or an unforeseen error in handling your request. We recommend retrying your request after some time. |