Error Handling

Error Response Format

All error responses follow a consistent JSON format:

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or expired.",
    "details": { }
  },
  "request_id": "req_abc123"
}

The details object is optional and provides additional context for specific error types (e.g., the required tier for a TIER_RESTRICTION error).

HTTP Status Codes

Error Codes

Authentication (401)

• AUTHENTICATION_REQUIRED- No API key provided in the request
• INVALID_API_KEY- The API key format is invalid or the key does not exist
• API_KEY_EXPIRED- The API key has passed its expiration date
• API_KEY_REVOKED- The API key has been revoked

Authorization (403)

• TIER_RESTRICTION- Endpoint requires a higher tier than your current plan
• IP_NOT_ALLOWED- Request IP is not in the key's allowlist
• SUBSCRIPTION_INACTIVE- Your subscription is expired or canceled

Validation (400)

• VALIDATION_ERROR- Input validation failed (check details for specifics)
• MISSING_PARAMETER- A required parameter was not provided
• INVALID_DOMAIN- The domain format is invalid
• INVALID_IP- The IP address format is invalid

Rate Limiting (429)

• RATE_LIMIT_EXCEEDED- Too many requests in the current window. Check Retry-After header.
• QUOTA_EXCEEDED- Monthly quota for this endpoint has been reached

Server Errors (500-504)

• EXTERNAL_SERVICE_ERROR- An upstream service (DNS resolver, RDAP, etc.) returned an error
• TIMEOUT- An upstream service did not respond in time
• CIRCUIT_OPEN- Service temporarily unavailable due to repeated upstream failures
• INTERNAL_ERROR- Unexpected server error. Contact support if persistent.