Error Handling

Error envelope

Every error response uses the same JSON shape:

{
  "error": {
    "code": "rate_limited",
    "message": "Sustained rate limit exceeded — retry after 12 seconds",
    "details": {
      "retry_after_seconds": 12,
      "tier": "pro",
      "limit_rpm_60s": 3000
    }
  }
}

code is a stable machine-readable identifier; message is human-readable and may change. Always switch on code, not message.

Status codes

Status	Code	Meaning	Retry?
`400`	`bad_request`	Malformed request body or invalid IP format	No — fix the request
`401`	`unauthorized`	API key / gateway auth missing or invalid	No — fix credentials
`403`	`forbidden`	Key tier does not permit this endpoint or field	No — upgrade tier
`404`	`not_found`	Resource doesn’t exist (rare)	No
`422`	`validation_error`	Pydantic validation failed	No — fix payload
`429`	`rate_limited`	Too many requests	Yes — see headers
`500`	`internal_error`	Unexpected server error	Yes — exponential backoff
`503`	`unhealthy`	Service degraded	Yes — exponential backoff

On the IP endpoints, a 400 bad_request carries a more specific code in the envelope — one of invalid_ip_reserved (RFC-reserved / non-global address), invalid_ip_integer_form (bare integer not accepted), or invalid_ip_format (unparseable). Switch on these subcodes when you need to distinguish why an IP was rejected.

Rate-limit headers

Every response carries the current rate-limit state:

X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 2997
X-RateLimit-Window: 60

A 429 response adds two headers telling you when to retry:

Retry-After: 12                 # seconds to wait
X-RateLimit-Reset: 1714339200   # Unix timestamp when the next slot frees

X-RateLimit-Limit is your request ceiling, expressed as requests per 60-second window (not per second). X-RateLimit-Remaining is how many requests remain in the current window. X-RateLimit-Window is the window length in seconds. On a 429, Retry-After is the recommended wait in seconds and X-RateLimit-Reset is the Unix timestamp when the next slot frees (≈ now + Retry-After). Because this is a sliding-window limiter, the exact reset instant is only defined at denial time, so X-RateLimit-Reset appears on 429 responses only — prefer Retry-After for backoff.

Retry strategy

For transient errors (429, 500, 503):

import httpx, time, random

def lookup_with_retry(ip, key, max_attempts=5):
    for attempt in range(max_attempts):
        resp = httpx.get(
            f"https://vpn-proxy-detection.whoisxmlapi.com/api/v1/ip/{ip}",
            params={"apiKey": key},
            timeout=10,
        )
        if resp.status_code == 200:
            return resp.json()
        if resp.status_code == 429:
            wait = int(resp.headers.get("Retry-After", 1))
            time.sleep(wait)
            continue
        if resp.status_code in (500, 503):
            backoff = 2 ** attempt + random.random()
            time.sleep(backoff)
            continue
        # 4xx other than 429 → don't retry
        resp.raise_for_status()
    raise RuntimeError(f"Exhausted {max_attempts} retries for {ip}")

Don’t retry 4xx errors other than 429. They indicate a problem with your request, and retrying just wastes quota.

Circuit breaking

For high-volume integrations, wrap calls in a circuit breaker so a brief outage doesn’t cascade into your application:

from circuitbreaker import circuit

@circuit(failure_threshold=5, recovery_timeout=30)
def lookup(ip, key):
    # ...

We aim for 99.5 % (Pro) / 99.9 % (Business) / 99.95 % (Enterprise) availability, but caller-side circuit breakers are still recommended.

Getting Started

Guides

Reference

Lookup

Aggregates

Bulk Exports

Error envelope

Status codes

Rate-limit headers

Retry strategy

Circuit breaking

​Error envelope

​Status codes

​Rate-limit headers

​Retry strategy

​Circuit breaking

Error envelope

Status codes

Rate-limit headers

Retry strategy

Circuit breaking