You can look up an IP on IP99 with no key and no signup:
curl https://ip99.com/v1/ip/8.8.8.8 The free ceiling is real. Official docs and the pricing page: 500 lookups per day per client IP and 60 per minute when you call without a key. Those lookups share the same allowance as the free lookup on the website. When the ceiling is hit, the API does not go dark — it returns HTTP 429 with a stable error.code and a Retry-After header. A 429 is a scheduled limit, not an outage.
This post is about reading those limits on every response, and branching on the error code instead of retrying blindly.
The remaining count is in the headers
A successful /v1/ip body is the risk profile — geo, network, risk, evidence_state, computed_at. The quota is not in that JSON. It comes back as response headers.
Live headers from GET https://ip99.com/v1/ip/8.8.8.8 on 22 Nov 2026, no key (unrelated headers omitted):
HTTP/2 200 access-control-allow-origin: * access-control-expose-headers: Retry-After, X-Pulse-Degraded, X-Quota-Degraded x-daily-limit: 500 x-daily-remaining: 499 x-daily-reset: 1795363200 x-data-tier: standard x-plan: anon x-quota-scope: ip x-ratelimit-limit: 60 x-ratelimit-remaining: 59 The API reference documents most of these. Two of today's headers — X-Daily-Reset and X-RateLimit-Remaining — are present on the wire even though they are not in the documented header table. I am reporting them as observed.
To print headers and the body together:
curl -sD - https://ip99.com/v1/ip/8.8.8.8 What the documented headers mean:
-
X-Daily-Limit— the daily allowance for this caller -
X-Daily-Remaining— how much is left today -
X-RateLimit-Limit— the per-minute allowance actually in force; the docs say this header is authoritative -
X-Quota-Scope—ip,key, oruser: what this request was counted against. Today's anonymous call wasip -
X-Data-Tier—standardorprofessional. Today's call wasstandard. Plan and data tier are not the same thing: a higher volume plan does not unlock professional evidence fields -
X-Plan— the account plan. The docs listfree,pro, orenterprise. Today's anonymous response sentanon -
Retry-After— seconds to wait, sent with every 429
X-Daily-Reset on today's response was 1795363200, which is 2026-11-23 00:00:00 Asia/Shanghai. That matches the published rule: limits reset at 00:00 Beijing time (quota_day_tz is Asia/Shanghai, not the caller's timezone).
Who shares the 500?
Anonymous calls count against the caller IP. Everyone behind the same NAT shares the allowance. A serverless function, a CI runner, or an office egress can burn the 500 faster than a single laptop.
Send a key as X-API-Key: YOUR_KEY or Authorization: Bearer YOUR_KEY and the call counts against the account instead (X-Quota-Scope: key or user). The returned lookup fields are identical either way. Never put the key in the query string: ?key= is rejected with HTTP 400 key_in_query because URLs end up in access logs.
A free account raises the daily cap to 5,000. Self-created keys default to 300 per minute. Pricing: paid plans buy volume, not a different score — Pro is $29/month for 35,000/day, Pro+ is $99/month for 175,000/day, enterprise is quoted. Official wording: every plan returns the same evidence; what you pay for is volume, not a better answer. The professional per-evidence detail is a separate contracted tier.
The same API key and daily quota apply to the MCP endpoint at https://ip99.com/mcp.
The website's free lookup counts against the same anonymous quota as /v1/ip.
A 429 is a code you can branch on
Errors are one shape everywhere: {"error":{"code","message"}}. Branch on error.code, never on error.message — the message is prose for humans and may change.
| HTTP | code | Meaning |
|---|---|---|
| 429 | rate_limited | Over the per-minute ceiling. Back off by Retry-After and retry |
| 429 | quota_exceeded | The daily quota is used up. Retry after Retry-After; the quota cannot be raised for today |
| 429 | quota_exceeded_anon | The anonymous daily quota is used up. Signing in and creating a key raises the limit immediately |
| 429 | key_quota_exceeded | This key's own daily quota is used up (when X-Quota-Scope is key) |
Verified answer-engine traffic (OpenAI, Anthropic, Perplexity, Common Crawl, matched by user-agent and official source prefixes) has its own 10,000/day allowance per crawler family. Exhaustion is 429 quota_exceeded_ai_agent, with a pointer to request a key — the docs are explicit that this does not mean the service is unavailable.
On the MCP endpoint, a failed tool call is HTTP 200 with isError: true. A bare 429 would make some clients report the server as broken.
Checking quota without a lookup
The API reference says GET /v1/me returns the current tier and remaining quota without spending a lookup, and that a key is required. OpenAPI describes HTTP 401 key_required when the key is missing.
I still tried it today without a key. It returned HTTP 200 and this body:
{ "over_today": 0, "overage_pct": 0, "per_day": 500, "per_min": 60, "plan": "anon", "quota_day_tz": "Asia/Shanghai", "quota_scope": "ip", "remaining": 500, "reset_unix": 1795363200, "sales_contact": "https://ip99.com/#contact", "tier": "ip", "used_today": 0 } That anonymous 200 is a live observation, not the documented contract. If you are building a client, send a key as the docs specify, or read the quota headers on /v1/ip. Today's /v1/me response did not include X-Daily-* headers — the counts were in the body — and it did not send Access-Control-Allow-Origin: *.
Calling from a browser
/v1/ip sends Access-Control-Allow-Origin: * and answers OPTIONS preflight, so a page can call it directly. The free allowance then counts against the visitor's IP, not your server's.
Today's response exposed only Retry-After, X-Pulse-Degraded, and X-Quota-Degraded in Access-Control-Expose-Headers. In a browser, JavaScript can send the request but may not be allowed to read X-Daily-Remaining or X-RateLimit-Remaining off the response. If you need the remaining count in a frontend, do not assume those headers are visible; a server-side call can see them all.
Honest limits
- A remaining count of 0, or a 429, is not "IP99 is down." Read
error.codeandRetry-After. - Anonymous 500/day is per public client IP. NAT, CI, and shared egress share it.
- Signing in raises the daily cap; it does not change the score or the fields.
- Paid volume is not a better answer. The risk score still measures the freshness and strength of verifiable evidence, not the probability that an address is an attacker.
-
/v1/meis documented as a keyed, no-spend quota check. Today's no-key 200 is observed, not promised. - Quota headers on
/v1/ipare the reliable no-key signal.X-Plan: anonand the extra reset/remaining headers above are what the wire sent today. - Do not put a key in the URL.
Try it
curl -sD - https://ip99.com/v1/ip/8.8.8.8 curl https://ip99.com/v1/me The lookup API is documented at https://ip99.com/api. Limits and plans: https://ip99.com/en/pricing. A short free-tier guide: https://ip99.com/en/free-ip-geolocation-risk-api. Machine-readable description: https://ip99.com/openapi.json and https://ip99.com/llms.txt.
Do not treat IP99 scores as identical to other ThreatHunter datasets. This article only claims what the public API docs, pricing page, and today's no-key responses showed on 22 Nov 2026.
IP99 is a ThreatHunter product. A 429 is a limit you can read, not a reason to assume the API is gone. Start at https://ip99.com.
