iplookupapi.com Documentation

# Request Status Codes

For all requests, we will return an HTTP status code that indicates a success or the problem that has led to the failure.

A successful request will be returned with status code 200

# API Error Codes

# 401

The request is not authenticated: no API key was sent (No API key found in request) or the key is invalid (Unauthorized).

# 403

You are not allowed to make this request — for example, the feature is not part of your plan (please upgrade your plan (opens new window)), the request's referrer is not on your API key's referrer whitelist, or the API key belongs to a different EverAPI product.

# 404

A requested endpoint does not exist, or no data is available for the requested IP address. The response message tells you which case you hit:

  • No route found — the requested endpoint does not exist, please check your request URL
  • No data found for this IP — your request was valid, but we have no data for the requested IP address

# 405

An HTTP method the endpoint does not take (error code method_not_allowed); the Allow header names those it does. A HEAD request answers 405 on every billed endpoint, without running it and without being billed; /v1/status and the other free endpoints answer HEAD like GET.

# 422

Validation error, please check the list of validation errors: here

# 429

You have hit your rate limit or your monthly limit. For more requests please upgrade your plan (opens new window).

# 500

Internal Server Error - let us know: support@iplookupapi.com

# Error response body

Errors are returned as JSON. Every error carries a human-readable message, and where available an info field links back to this page. Responses with status 401, 403, 404 and 429 additionally carry a machine-readable error envelope, so scripts and AI agents always get a next step. 422 validation errors and 500 errors do not carry the envelope — they only include message (plus errors and info for validation errors):

{
    "message": "You used all your monthly requests. Please upgrade your plan at https://app.iplookupapi.com/upgrade",
    "error": {
        "code": "quota_exceeded",
        "message": "You used all your monthly requests. Please upgrade your plan at https://app.iplookupapi.com/upgrade"
    },
    "quota": {
        "limit": 150,
        "used": 150,
        "remaining": 0,
        "resets_at": "2026-09-01T00:00:00+00:00"
    },
    "actions": {
        "upgrade": "https://app.iplookupapi.com/upgrade?utm_source=api_error&utm_campaign=quota_exceeded",
        "docs": "https://iplookupapi.com/docs/openapi.yaml"
    }
}
Field Description
error.code A stable, machine-readable error code, e.g. invalid_api_key, quota_exceeded, rate_limit_exceeded, not_found or forbidden
error.message The same human-readable message as the top-level message
quota Only present on quota errors: the limit, used and remaining requests of the exhausted quota, plus resets_at (ISO 8601 timestamp of the next reset, or null)
actions URLs for the most useful next steps, e.g. upgrade (change your plan) on quota errors, or sign_up and docs on authentication errors

The envelope fields are additive — the existing message and info fields are unchanged, so treat error, quota and actions as optional when parsing error responses.

# Validation errors

# Invalid IP

The ip field must be a valid IP address

# Invalid language

The selected language is invalid
Supported values: de, en, es, fr, ja, pt, ru, zh

# Invalid hostname

The hostname field must be 0, 1, true or false

# Invalid batch address

No entry of ips on the batch endpoint (opens new window) is a valid IP address. The error keys name their positions, e.g. ips.1. A batch with at least one valid address answers 200 and lists the others in errors.

# Batch too large

A batch can contain at most 1,000 IP addresses in a POST body, and 100 in the query string (e.g. A batch can contain at most 100 IP addresses in the query string, and up to 1000 in a POST body ({"ips": [...]}).)

← Testing →