Request Status Codes

You can tell if your request was successful by checking the status code when receiving an API response. If a response comes back unsuccessful, you can use the error type and error message to figure out what has gone wrong and do some rudimentary debugging (before contacting support). A successful request will be returned with status code 200.

Before reaching out to support with an error, please be aware that 99% of all reported errors are, in fact, user errors. Therefore, please carefully check your code before contacting ipbase support.

Status codes

Here is a list of the different categories of status codes returned by the ipbase API. Use these to understand if a request was successful.

Name
200
Type
Description
A 200 status code indicates a successful response.
Name
401
Type
Description
A 401 status code indicates that the API key you supplied is invalid (error.code invalid_api_key; double-check the key against your dashboard), or that the endpoint needs a key and the request had none (missing_api_key). Without a key, only /v2/info and /v2/status answer, up to 10 an hour per IP address; batches and every other endpoint need a key, which is free. A 401 is not billed.
Name
403
Type
Description
A 403 status code indicates that you are not allowed to use this endpoint, please upgrade your plan. When your plan does not include the endpoint, error.code is plan_upgrade_required and actions.upgrade opens the plans. It is not counted against your quota.
Name
404
Type
Description
A 404 status code indicates that a requested endpoint does not exist, that the requested ASN is unknown, or that we have no data for the requested IP address (No data found for this IP).
Name
405
Type
Description
A 405 status code indicates 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; /v2/status and the other free endpoints answer HEAD like GET.
Name
422
Type
Description
A 422 status code indicates that one or more request parameters failed validation — for example an invalid ip or an unsupported language. The response body contains a message and an errors object describing each rejected parameter (see below).
Name
429
Type
Description
A 429 status code indicates that you have hit your rate limit or your monthly limit. For more requests please upgrade your plan. A batch your quota cannot cover is refused before any address is looked up; quota.required in the response is what it needed.
Name
500
Type
Description
A 500 status code indicates an internal server error - let us know: support@ipbase.com

Error responses

Every error response is JSON and always contains a human-readable message. Responses with status 401, 403, 404 and 429 additionally carry a machine-readable envelope: an error object with a stable code, an actions object with URLs for the most useful next steps and — for quota errors — a quota object with your current usage. Where available, an info field links back to this page.

Example 422 response

{
    "message": "Validation error",
    "errors": {
        "ip": [
            "The ip field must be a valid IP address."
        ]
    },
    "info": "For more information, see documentation: https://ipbase.com/docs/status-codes/#_422"
}

Example 429 response with error envelope

{
    "message": "You used all your monthly requests. Please upgrade your plan at https://app.ipbase.com/upgrade",
    "error": {
        "code": "quota_exceeded",
        "message": "You used all your monthly requests. Please upgrade your plan at https://app.ipbase.com/upgrade"
    },
    "quota": {
        "limit": 150,
        "used": 150,
        "remaining": 0,
        "resets_at": "2026-11-01T00:00:00+00:00"
    },
    "actions": {
        "upgrade": "https://app.ipbase.com/upgrade?utm_source=api_error&utm_campaign=quota_exceeded&team=7123456789012345678",
        "pricing": "https://api.ipbase.com/v1/agent/plans",
        "docs": "https://ipbase.com/docs/llms.txt",
        "openapi": "https://ipbase.com/docs/openapi.yaml"
    }
}

The actions depend on the error. Quota, rate limit and plan errors carry upgrade (the plans of your account) and pricing (every plan as JSON). A grace_quota_exceeded also carries complete_payment, and a quota_exceeded carries enable_overage when your plan can turn on overage. Other errors, such as an unknown API key or ASN, carry agent_setup (the setup steps for AI coding agents), get_api_key (an approval link: a human approves a key on app.ipbase.com), sign_up and pricing. Every envelope also carries docs (the docs' llms.txt) and openapi (the OpenAPI specification).

Error codes you may encounter include invalid_api_key, quota_exceeded, grace_quota_exceeded, overage_quota_exceeded, rate_limit_exceeded, plan_upgrade_required, not_found and forbidden.

Validation errors

If your request fails with a 422 status code, the errors object in the response body tells you exactly which parameter was rejected and why. These are the most common validation errors:

Name
Invalid IP
Type
Description
The ip field must be a valid IP address.
Name
Invalid language
Type
Description
The selected language is invalid. Supported values: de, en, es, fr, ja, pt, ru, zh.
Name
Invalid batch address
Type
Description
No entry of ips on the batch endpoint 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.
Name
Batch too large
Type
Description
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": [...]}).).