Documentation

Errors

One error envelope shared by every product on the platform.

Envelope

Failures always answer with an error object carrying a stable machine-readable code and a human-readable message. Branch on code, never on the message text.

401 Unauthorized

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid."
  }
}

Codes you should handle

Status	Code	Meaning
400	invalid_ip	The address is not valid IPv4 or IPv6.
401	invalid_api_key	Missing, unknown, disabled or revoked key.
403	product_access_denied	The key belongs to a different product.
403	subscription_inactive	No active subscription for this product.
422	ip_lookup_unavailable	The address could not be resolved.
429	rate_limit_exceeded	Per-minute limit reached. Retry-After applies.
429	monthly_limit_exceeded	Monthly quota reached until the period resets.
500	internal_error	Unexpected failure. Safe to retry once.

Quota errors carry context

429 Too Many Requests

{
  "error": {
    "code": "monthly_limit_exceeded",
    "message": "Your monthly API request limit has been reached.",
    "limit": 100000,
    "usage": 100000
  }
}