Table of Contents
Request limits
The current application limiter allows up to 500 requests per minute per caller IP per service instance. This is the implementation's present limit, not a guaranteed global allowance: shared addresses share a budget, and infrastructure can impose additional limits.
Bulk requests accept 1–100 unique IP addresses. Empty, oversized or duplicate-address arrays are rejected. The current limiter counts HTTP requests; a shared quota weighted by the number of lookups remains planned. No API key is required to access these endpoints.
Responses report the limit in X-RateLimit-Limit, what remains in X-RateLimit-Remaining, and the seconds until it resets in X-RateLimit-Reset. Browser clients can read these headers and Retry-After. On HTTP 429, honor the Retry-After header before retrying. Use bounded backoff for temporary server failures and avoid retrying invalid input unchanged.
Errors
| HTTP status | Meaning | What to do |
|---|---|---|
| 400 | Invalid request or address | Correct the address or request shape. |
| 404 | No matching location, or unknown route | Check the route and allow for missing data. |
| 429 | Rate limit reached | Wait for the time in Retry-After. |
| 500 | Lookup or service failure | Retry with bounded backoff; handle unavailable data. |
| 503 | An optional service, such as correction storage, is unavailable | Defer that operation and try later. |
For example, an invalid single-address lookup can return:
{
"statusCode": 400,
"error": "Bad Request",
"message": "Invalid IP Address"
}
For a bulk request, inspect every entry in data for type: "error" and errorMessage, even when the HTTP status is 200.
A message describes your request, such as an invalid address or a failed validation. When the service fails unexpectedly, the response carries only the standard reason for its status, such as Internal Server Error, and a failed bulk entry reads Unable to lookup IP; the details stay in the service's logs.
Cache and browser clients
Successful single lookups expose X-Cache: HIT or MISS. This describes the service's lookup cache, not the accuracy or freshness of a location estimate. Responses from GET /ip, errors included, describe the caller and are sent with Cache-Control: no-store; do not cache them in a shared CDN or proxy.
Browser requests are allowed from origins configured for the deployment. Requests do not use credentials. A working command-line request does not imply that an arbitrary browser origin has CORS access.