Errors & limits

Errors, usage & quotas

Error codes

Code	Meaning
`400`	Invalid `POST` body or unsupported bulk request format.
`401`	Missing API key, or the `tag` parameter exceeds 20 characters.
`402`	API key is invalid or has reached its monthly request limit.
`403`	API key origin, referrer, or client-IP restriction rejected the request.
`404`	API key not found, or an individual IP could not be resolved (returned inside the results array as `{ "code": 404, "query_ip_address": "..." }`).
`413`	Bulk request exceeds the 1,000-address limit.
`429`	Per-client-IP rate limit exceeded for a key that enables the rate-limit option.

A field is missing from my response

Fields your plan does not include are omitted from the result object. They are never returned as null and never raise an error — a null would silently coerce to 0 in most languages, which for a field like risk_score would read as “perfectly safe” and quietly break a fraud rule.

Three things tell you what happened:

gated_fields — an array on the result listing exactly what was withheld. When you use fields=, it lists only the fields you asked for and did not get.
gated_fields_info — a link to the field comparison.
X-IpQuery-Plan — a response header naming the plan the request resolved to. Present on every response; check it with curl -I.

For example, requesting a paid field on the free plan:

[
  {
    "query_ip_address": "8.8.8.8",
    "country": "United States",
    "gated_fields": ["risk_score"],
    "gated_fields_info": "Some fields are not included on your plan. See https://ipquery.info/pricing#fields"
  }
]

See which fields each plan includes. The 15 day free trial returns the complete dataset.

Usage, plans & quotas

Each plan includes a monthly request allowance. One single-IP request counts as one unit; a batch ipList or POST request counts as one unit per address, up to 1,000 addresses per request. Your remaining allowance and reset cycle are always visible on your Statistics dashboard.

Plan	Requests / month	Price
Free trial	1,000	15 days, no card required
Basic	100,000	$10 / month
Advanced	1,500,000	$50 / month
Enterprise	5,000,000	$100 / month

When a key exhausts its monthly allowance the API responds with 402 until the cycle resets or you upgrade on the Account & Billing page. See Pricing for full plan details.

Per-IP rate limiting

For keys used from the browser you can enable Rate Limit by IP Address on the API Keys page, which throttles any single caller to one request every five minutes — protecting your allowance from abuse without a back end.

Tagging requests

Add a tag (max 20 characters) to single-address requests to segment your usage analytics by campaign, product, or traffic source. Tags appear as filters on your Statistics dashboard.

Machine-readable spec

An OpenAPI 3.1 description of the GET and POST API is available at https://ipquery.info/openapi.yaml for use with code generators and API tooling.