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. Double-check the key against your dashboard.
Name
403
Type
Description
A 403 status code indicates that you are not allowed to use this endpoint, please upgrade your plan.
Name
404
Type
Description
A 404 status code indicates that a requested endpoint does not exist, or that no data was found for the requested IP or ASN.
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.
Name
500
Type
Description
A 500 status code indicates a internal server error - let us know: [email protected]

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

Error codes you may encounter include missing_api_key, invalid_api_key, quota_exceeded, grace_quota_exceeded, overage_quota_exceeded, rate_limit_exceeded, 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
Missing IP
Type
Description
The ip parameter is required.
Name
Invalid language
Type
Description
The selected language is invalid and should be an ISO Alpha 2 Language Code for localising the ip data.