# 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 (Invalid authentication credentials).

# 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

# 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/subscription",
    "error": {
        "code": "quota_exceeded",
        "message": "You used all your monthly requests. Please upgrade your plan at https://app.iplookupapi.com/subscription"
    },
    "quota": {
        "limit": 300,
        "used": 300,
        "remaining": 0,
        "resets_at": "2026-09-01T00:00:00+00:00"
    },
    "actions": {
        "upgrade": "https://app.iplookupapi.com/subscription?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 true or false