Error handling

Error codes

Response bodies

200 — Validation error

{
    "ErrorMessage": {
        "errorCode": "WHOIS_01",
        "msg": "mutually exclusive cache flags: preferFresh and _hardRefresh cannot be used together"
    }
}

200 — Unable to retrieve WHOIS record

{
    "ErrorMessage": {
        "errorCode": "WHOIS_03",
        "msg": "Unable to retrieve whois record"
    }
}

401 — Missing API key

{
    "ErrorMessage": {
        "errorCode": "AUTHENTICATE_04",
        "msg": "API key required (Authorization: Bearer key or apiKey field)"
    }
}

401 — Unknown user

{
    "ErrorMessage": {
        "errorCode": "WHOIS_02",
        "msg": "unknown user"
    }
}

401 — No subscription / no credits remaining

{
    "ErrorMessage": {
        "errorCode": "AUTHENTICATE_05",
        "msg": "no credits remaining"
    }
}

403 — IP not on allowlist

{
    "ErrorMessage": {
        "errorCode": "AUTHENTICATE_10",
        "msg": "Your IP address is not added to the IP allowlist (https://user.whoisxmlapi.com/settings/ip-allow-list). The request is rejected."
    }
}

429 — Rate limit exceeded (with a Retry-After header)

{
    "ErrorMessage": {
        "errorCode": "AUTHENTICATE_06",
        "msg": "rate limit exceeded"
    }
}

5xx — Server error

{
    "ErrorMessage": {
        "errorCode": "WHOIS_01",
        "msg": "Internal server error"
    }
}

The error body is described by the error JSON Schema and the error XSD.