Error Handling

The API uses standard HTTP status codes and returns structured error responses.

Error response format

{
  "error": {
    "code": "error_code",
    "message": "Human-readable error description"
  },
  "request_id": "req_abc123"
}

HTTP status codes

| Status | Meaning | When | |---|---|---| | 200 | OK | Request succeeded | | 400 | Bad Request | Missing or invalid parameters | | 401 | Unauthorized | Invalid or missing API key | | 429 | Too Many Requests | Rate limit exceeded | | 500 | Internal Server Error | Server-side error |

Error codes

bad_request

The request is missing required parameters or contains invalid data.

{
  "error": {
    "code": "bad_request",
    "message": "email or domain parameter is required"
  }
}

Common causes:

• Missing both email and domain query parameters
• Invalid email format

unauthorized

The API key is missing, invalid, or revoked.

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Common causes:

• Missing Authorization header
• Incorrect Bearer prefix
• Revoked or deleted API key

rate_limited

You've exceeded the rate limit for your plan.

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

Check the X-RateLimit-Reset header to know when you can retry. See Rate Limits for details.

internal_error

An unexpected error occurred on our side.

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error"
  }
}

If this persists, contact support with your request_id.

Best practices

1. Always check the HTTP status code before parsing the response body
2. Implement exponential backoff for 429 and 500 errors
3. Log the request_id for debugging and support requests
4. Handle network errors gracefully — timeouts, DNS failures, etc.