# 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

Invalid authentication credentials

# 403

You are not allowed to use this endpoint, please upgrade your plan (opens new window).

# 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