freeiplookupapi.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

Your API key is missing or invalid. A missing key returns the message No API key found in request (error.code: missing_api_key); an invalid key returns Invalid authentication credentials (error.code: invalid_api_key).

# 403

You are not allowed to use this endpoint with your API key. Either the key belongs to a different EverAPI product (error.code: key_not_allowed_for_product) — use your freeiplookupapi API key, which you find in your dashboard (opens new window) — or the request's referrer is not on the API key's referrer whitelist (error.code: referrer_not_allowed).

# 404

A requested endpoint does not exist

# 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@freeiplookupapi.com

# Error Response Body

All errors are returned as JSON. In addition to the human-readable message, 401, 403, 404 and 429 responses carry a machine-readable envelope with a stable error.code and actionable next steps in actions — quota errors additionally include a quota object. For example, a 429 after exhausting the monthly quota:

{
    "message": "You used all your monthly requests. Please upgrade your plan at https://app.freeiplookupapi.com/subscription",
    "error": {
        "code": "quota_exceeded",
        "message": "You used all your monthly requests. Please upgrade your plan at https://app.freeiplookupapi.com/subscription"
    },
    "quota": {
        "limit": 5000,
        "used": 5000,
        "remaining": 0,
        "resets_at": "2026-09-01T00:00:00+00:00"
    },
    "actions": {
        "upgrade": "https://app.freeiplookupapi.com/subscription?utm_source=api_error&utm_campaign=quota_exceeded",
        "docs": "https://freeiplookupapi.com/docs/openapi.yaml"
    }
}

Common error.code values are missing_api_key, invalid_api_key, key_not_allowed_for_product, referrer_not_allowed, quota_exceeded, grace_quota_exceeded, overage_quota_exceeded, rate_limit_exceeded, not_found and forbidden. The actions object contains URLs you (or your AI agent) can follow to resolve the error, e.g. upgrade, sign_up or docs. Errors generated at the gateway (missing or invalid API key, the minute rate limit) carry error.code and actions as well — they just never include a quota object.

# Validation errors

# Invalid Ip

The ip must be a valid IP address

# Missing ip

The ip parameter is required