WhoisXML API WHOIS / WHOIS History

https://whois.whoisxmlapi.com/documentation/
Admin
Provides current and historical ownership information on domains and IPs, identifying connections...
Tokens:15,141
Snippets:92
Trust Score:9.9
Update:20 hours ago
Show doc for...
Tokens:
Raw
### GET WHOIS API with access token

Source: https://whois.whoisxmlapi.com/documentation/oauth

Example of a GET request to the WHOIS API using an access token for authentication.

```APIDOC
## GET WHOIS API with access token

### Description
Example of a GET request to the WHOIS API using an access token for authentication.

### Method
GET

### Endpoint
https://www.whoisxmlapi.com/whoisserver/WhoisService?domainName=google.com

### Headers
- **Authorization** (string) - Required - Bearer token. Use the access token obtained from the OAuth token endpoint.

### Request Example
```
curl --location 'https://www.whoisxmlapi.com/whoisserver/WhoisService?domainName=google.com' \
--header 'Authorization: Bearer %accessToken%'
```
```

--------------------------------

### GET /whoisserver/WhoisService

Source: https://whois.whoisxmlapi.com/documentation/making-requests

Makes a WHOIS request using the GET method with query parameters. Requires an API key and a domain name.

```APIDOC
## GET /whoisserver/WhoisService

### Description
Makes a WHOIS request using the GET method with query parameters. Requires an API key and a domain name.

### Method
GET

### Endpoint
https://www.whoisxmlapi.com/whoisserver/WhoisService

### Parameters
#### Query Parameters
- **apiKey** (string) - Required - Your API key for authentication.
- **domainName** (string) - Required - The domain name to query.

### Request Example
https://www.whoisxmlapi.com/whoisserver/WhoisService?apiKey=API_KEY&domainName=google.com

### Response
#### Success Response (200)
Returns WHOIS/RDAP registration details in XML or JSON format.

#### Response Example
(Response format not specified in source.)
```

--------------------------------

### GET /user-service/account-balance

Source: https://whois.whoisxmlapi.com/documentation/account-balance-information

Retrieves account balance information using a GET request with the API key as a query parameter.

```APIDOC
## GET https://user.whoisxmlapi.com/user-service/account-balance?apiKey=API_KEY

### Description
Retrieves account balance information for the authenticated user.

### Method
GET

### Endpoint
https://user.whoisxmlapi.com/user-service/account-balance

### Parameters
#### Query Parameters
- **apiKey** (string) - Required - Your personal API key.
- **productId** (string) - Optional - A list of product IDs can be found in the response.
- **outputFormat** (string) - Optional - Response output format. Acceptable values: JSON | XML. Default: JSON.

### Response
#### Success Response (200)
- **accountBalance** (object) - Contains account balance details.
- **productId** (string) - Product identifier.
- **credits** (number) - Number of credits available.

#### Response Example
{
  "accountBalance": {
    "productId": "whoisapi",
    "credits": 12345
  }
}
```

--------------------------------

### POST WHOIS API with access token

Source: https://whois.whoisxmlapi.com/documentation/oauth

Example of a POST request to the WHOIS API using an access token for authentication.

```APIDOC
## POST WHOIS API with access token

### Description
Example of a POST request to the WHOIS API using an access token for authentication.

### Method
POST

### Endpoint
https://www.whoisxmlapi.com/whoisserver/WhoisService

### Headers
- **Content-Type** (string) - Required - application/json
- **Authorization** (string) - Required - Bearer token. Use the access token obtained from the OAuth token endpoint.

### Request Body
- **domainName** (string) - Required - The domain name to query.

### Request Example
```
curl --location 'https://www.whoisxmlapi.com/whoisserver/WhoisService' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer %accessToken%' \
    --data '{
        "domainName": "google.com"
    }'
```
```

--------------------------------

### OAuth error response - 401

Source: https://whois.whoisxmlapi.com/documentation/oauth

Example error response when the API key is invalid or the credits balance is insufficient.

```json
{
    "code": 401,
    "messages": "Access restricted. Check the credits balance or enter the correct API key."
}
```

--------------------------------

### cURL WHOIS API POST request with access token

Source: https://whois.whoisxmlapi.com/documentation/oauth

Example of a POST request to the WHOIS API using the access token in the Authorization header.

```bash
curl --location 'https://www.whoisxmlapi.com/whoisserver/WhoisService' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer %accessToken%' \
    --data '{
        "domainName": "google.com"
    }'
```

--------------------------------

### Access token response

Source: https://whois.whoisxmlapi.com/documentation/oauth

Example JSON response from the OAuth endpoint. The accessToken value is used as the apiKey parameter in subsequent API requests.

```json
{
    "accessToken": "G2OIE2AKRCVDYFUJCV5PXXXXXXXXXXXX",
    "expiresIn": 7200
}
```

--------------------------------

### cURL request with an Authorization header

Source: https://whois.whoisxmlapi.com/documentation/making-requests

Example of a cURL request to the WhoisXML API using an Authorization header for authentication.

```APIDOC
## GET https://www.whoisxmlapi.com/whoisserver/WhoisService?domainName=google.com

### Description
Sends a WHOIS lookup request to the WhoisXML API using an Authorization header for authentication.

### Method
GET

### Endpoint
https://www.whoisxmlapi.com/whoisserver/WhoisService?domainName=google.com

### Parameters
#### Query Parameters
- **domainName** (string) - Required - The domain name to query.

#### Headers
- **Authorization** (string) - Required - Bearer token (API key or OAuth access token).

### Request Example
```
curl --location 'https://www.whoisxmlapi.com/whoisserver/WhoisService?domainName=google.com' \
--header 'Authorization: Bearer %accessToken%'
```

### Response
No response details are provided in the source.
```

--------------------------------

### GET https://user.whoisxmlapi.com/user-service/api-key/generate

Source: https://whois.whoisxmlapi.com/documentation/generate-new-api-key

Generates a new API key for the user. The current API key is required as a query parameter. The response contains the newly generated API key.

```APIDOC
## GET https://user.whoisxmlapi.com/user-service/api-key/generate

### Description
Generates a new API key for the user. The current API key is required as a query parameter. The response contains the newly generated API key.

### Method
GET

### Endpoint
https://user.whoisxmlapi.com/user-service/api-key/generate

### Parameters
#### Query Parameters
- **currentApiKey** (string) - Required - Your personal API key. Get it on the My products page.
- **outputFormat** (string) - Optional - Response output format. Acceptable values: JSON | XML. Default: JSON.

### Response
#### Success Response (200)
- **apiKey** (string) - Generated API key.

#### Response Example
```json
{
   "apiKey": "at_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
```

### Error Codes
- **400 Bad Request** - The API key you entered does not exist or is no longer active.
- **422 Unprocessable Entity** - Input correct request parameters.
```

--------------------------------

### OAuth error response - 422

Source: https://whois.whoisxmlapi.com/documentation/oauth

Example error response when the grantType parameter is invalid.

```json
{
    "code": 422,
    "messages": {
        "grantType": [
            "The selected grant type is invalid."
        ]
    }
}
```

--------------------------------

### cURL request with Authorization header

Source: https://whois.whoisxmlapi.com/documentation/making-requests

Sends a GET request to the WhoisXML API with an Authorization header using a Bearer token. Replace '%accessToken%' with your OAuth access token.

```bash
curl --location 'https://www.whoisxmlapi.com/whoisserver/WhoisService?domainName=google.com' \
--header 'Authorization: Bearer %accessToken%'
```

--------------------------------

### cURL request with body in JSON format

Source: https://whois.whoisxmlapi.com/documentation/making-requests

Example of a cURL request to the WhoisXML API using a JSON request body containing the domain name and API key.

```APIDOC
## POST https://www.whoisxmlapi.com/whoisserver/WhoisService

### Description
Sends a WHOIS lookup request to the WhoisXML API using a JSON request body.

### Method
POST

### Endpoint
https://www.whoisxmlapi.com/whoisserver/WhoisService

### Parameters
#### Request Body
- **domainName** (string) - Required - The domain name to query.
- **apiKey** (string) - Required - Your personal API key.

### Request Example
```json
{
    "domainName": "google.com",
    "apiKey": "API_KEY"
}
```

### Response
No response details are provided in the source.
```

--------------------------------

### POST /whoisserver/WhoisService

Source: https://whois.whoisxmlapi.com/documentation/making-requests

Makes a WHOIS request using the POST method with a JSON body. Requires an API key and a domain name.

```APIDOC
## POST /whoisserver/WhoisService

### Description
Makes a WHOIS request using the POST method with a JSON body. Requires an API key and a domain name.

### Method
POST

### Endpoint
https://www.whoisxmlapi.com/whoisserver/WhoisService

### Parameters
#### Request Body
- **apiKey** (string) - Required - Your API key for authentication.
- **domainName** (string) - Required - The domain name to query.

### Request Example
{
  "apiKey": "API_KEY",
  "domainName": "google.com"
}

### Response
#### Success Response (200)
Returns WHOIS/RDAP registration details in XML or JSON format.

#### Response Example
(Response format not specified in source.)
```

--------------------------------

### Generate access token with cURL

Source: https://whois.whoisxmlapi.com/documentation/oauth

Use this cURL command to request an access token from the OAuth endpoint. The Authorization header must contain the base64-encoded API key. The expiresIn parameter is optional and defaults to 3600 seconds.

```bash
curl --location 'https://main.whoisxmlapi.com/oauth/token' \
--header 'Authorization: Bearer %base64_encoded_API_key%' \
--header 'Content-Type: application/json' \
--data '{
    "grantType": "access_token",
    "expiresIn": 7200
}'
```

--------------------------------

### WHOIS API Lookup Parameters

Source: https://whois.whoisxmlapi.com/documentation/making-requests

Describes the input parameters for the WHOIS API lookup endpoint, including required and optional parameters.

```APIDOC
## WHOIS API Lookup Parameters

### Description
This documentation covers the input parameters for the WHOIS API. The required parameter is `domainName`, and there are several optional parameters that control the protocol, caching, and output format.

### Parameters

#### Required Parameters
- **domainName** (string) - Required - The domain/IPv4/IPv6/email address for which WHOIS or RDAP data is requested.

#### Optional Parameters
- **rdap** (integer) - Optional - Acceptable values: 0, 1, 2. Default: 0. 0 retrieves data via Auto protocol, 1 via RDAP, 2 via WHOIS. Note: RDAP is not supported for all TLDs.
- **maxCacheAgeHours** (integer) - Optional - Acceptable values: integer ≥ -1. Default: 168. Maximum acceptable age of a cached record in hours. 0 requests freshest record, -1 returns cached data of any age. Values 0 to 47 cost 5 credits, -1 costs 1 credit, 48 and up or not set costs 1 credit.
- **preferFresh** (integer/boolean) - Optional - Acceptable values: 0, 1, true, false. Default: 0. 1 narrows acceptable cache age to 48 hours. Cannot be combined with _hardRefresh.
- **_hardRefresh** (integer/boolean) - Optional - Acceptable values: 0, 1, true, false. Default: 0. 1 provides real-time data at a cost of 5 credits, narrowing acceptable cache age to 24 hours. Cannot be combined with preferFresh.
- **_dbOnly** (integer/boolean) - Optional - Acceptable values: 0, 1, true, false. Default: 0. 1 reads cached data only, or returns error WHOIS_03 if no cached data.
- **exactMatch** (integer/boolean) - Optional - Acceptable values: 0, 1, true, false. Default: 0. For IP lookups only, enables RPSL exact-match (-x). Ignored for domain lookups.
- **ignoreRawTexts** (integer/boolean) - Optional - Acceptable values: 0, 1, true, false. Default: 0. 1 strips all raw text from output (rawText, header, footer, strippedText, and rawText of name servers and contacts).
- **cmd** (string) - Optional - Acceptable values: GET_DN_AVAILABILITY (case-insensitive). Returns compact DomainInfo response instead of full record. Any other value returns normal record.
- **outputFormat** (string) - Optional - Acceptable values: JSON, XML (case-insensitive). Default: XML. Unrecognized values fall back to XML.

### Notes
- Unknown parameters are ignored; sending an unrecognized parameter does not cause an error.
- The Auto protocol retrieves the best data available from either RDAP or WHOIS based on ongoing technical tests and server monitoring across TLDs.
- Monitoring of top-level domains across RDAP and WHOIS protocols: https://rdap.wxapros.com/
```

--------------------------------

### POST /user-service/account-balance

Source: https://whois.whoisxmlapi.com/documentation/account-balance-information

Retrieves account balance information using a POST request with parameters in the request body.

```APIDOC
## POST https://user.whoisxmlapi.com/user-service/account-balance

### Description
Retrieves account balance information for the authenticated user.

### Method
POST

### Endpoint
https://user.whoisxmlapi.com/user-service/account-balance

### Parameters
#### Request Body
- **apiKey** (string) - Required - Your personal API key.
- **productId** (string) - Optional - A list of product IDs can be found in the response.
- **outputFormat** (string) - Optional - Response output format. Acceptable values: JSON | XML. Default: JSON.

### Request Example
{
  "apiKey": "YOUR_API_KEY",
  "productId": "whoisapi",
  "outputFormat": "JSON"
}

### Response
#### Success Response (200)
- **accountBalance** (object) - Contains account balance details.
- **productId** (string) - Product identifier.
- **credits** (number) - Number of credits available.

#### Response Example
{
  "accountBalance": {
    "productId": "whoisapi",
    "credits": 12345
  }
}
```

--------------------------------

### POST /oauth/token

Source: https://whois.whoisxmlapi.com/documentation/oauth

Generates an access token for server-to-server OAuth authentication. The token is used instead of the apiKey parameter in API requests.

```APIDOC
## POST /oauth/token

### Description
Generates an access token for server-to-server OAuth authentication. The token is used instead of the apiKey parameter in API requests.

### Method
POST

### Endpoint
https://main.whoisxmlapi.com/oauth/token

### Headers
- **Authorization** (string) - Required - Base64 encoded API key. Authentication scheme: Bearer.
- **Content-Type** (string) - Required - application/json

### Parameters
#### Request Body
- **grantType** (string) - Required - The grant type to generate an access token. Acceptable values: access_token.
- **expiresIn** (integer) - Optional - The lifetime of the access token in seconds. Acceptable values: 1800, 3600, 7200, 10800. Default: 3600.
- **outputFormat** (string) - Optional - Response output format. Acceptable values: JSON | XML. Default: JSON.

### Request Example
```
curl --location 'https://main.whoisxmlapi.com/oauth/token' \
--header 'Authorization: Bearer %base64_encoded_API_key%' \
--header 'Content-Type: application/json' \
--data '{
    "grantType": "access_token",
    "expiresIn": 7200
}'
```

### Response
#### Success Response (200)
- **accessToken** (string) - The access token to use for authentication.
- **expiresIn** (integer) - The lifetime of the access token in seconds.

#### Response Example
```
{
    "accessToken": "G2OIE2AKRCVDYFUJCV5PXXXXXXXXXXXX",
    "expiresIn": 7200
}
```

#### Error Response (401)
- **code** (integer) - Error code.
- **messages** (string) - Error message.

#### Error Response Example (401)
```
{
    "code": 401,
    "messages": "Access restricted. Check the credits balance or enter the correct API key."
}
```

#### Error Response (422)
- **code** (integer) - Error code.
- **messages** (object) - Validation errors.

#### Error Response Example (422)
```
{
    "code": 422,
    "messages": {
        "grantType": [
            "The selected grant type is invalid."
        ]
    }
}
```
```

--------------------------------

### Authentication

Source: https://whois.whoisxmlapi.com/documentation/making-requests

Describes the required authentication methods for the WhoisXML API: via the apiKey query parameter or via the Authorization header.

```APIDOC
## Authentication

### Description
All requests to the WhoisXML API require authentication using either a personal API key or a Server-to-Server OAuth token.

### Methods

#### Via the query parameter
- **apiKey** (string) - Required - Your personal API key. Get it from the My products page.

#### Via the header
- **Authorization** (string) - Required - API key or Server-to-Server OAuth token. Authentication scheme: Bearer.

### Notes
- The **apiKey** query parameter has the highest priority. If provided, the service ignores the **Authorization** header.

### Examples
- `Authorization: Bearer %API_KEY%`
- `Authorization: Bearer %OAUTH_ACCESS_TOKEN%`
```

--------------------------------

### WHOIS API Output Parameters

Source: https://whois.whoisxmlapi.com/documentation/output

Describes the possible values of the output parameter that indicates the status of a WHOIS/RDAP lookup, including error codes and their meanings.

```APIDOC
## WHOIS API Output Parameters

### Description
This section describes the possible values of the output parameter that indicates the status of a WHOIS/RDAP lookup. Each value provides information about the domain registration status and whether a retry is needed.

### Output Parameters

- **_MISSING_WHOIS_DATA_** - domain is not registered; no need to retry fetching the data.
- **_RESERVED_DOMAIN_NAME_** - This is related to reserved domains like example.com or nic.${tld}. A complete description can be found here: [www.iana.org/domains/reserved](https://www.iana.org/domains/reserved).
- **_MASKED_WHOIS_DATA_** - domain is registered; we successfully retrieved the WHOIS or RDAP record, yet some fields are masked. No need to retry.
- **_NO_DATA_** - we have been throttled by the WHOIS or RDAP server, so we don't know whether the domain exists or not. Need to retry fetching the data. **No credit is charged when this error code is returned unless the API request was made with the input parameter _\_hardRefresh_.**
- **_INCOMPLETE_DATA_** - the domain is registered, but we received only a thin WHOIS/RDAP record. Various fields are missing, and there is no assurance which ones are present.
- **_PARTIAL_DATA_** - the WHOIS/RDAP data response for this domain is partial. We obtained a thin record from the Registry, but the Registrar’s RDAP/WHOIS service is not supplying full details at this time. This is a Registrar-side limitation that affects all queries for this domain at that Registrar, and it usually resolves once the Registrar updates its thick WHOIS/RDAP data (this may take anywhere from hours to weeks). However, unlike **_INCOMPLETE_DATA_**, the response includes a predictable baseline set of fields: **_registrarName, createdDate, updatedDate, expiresDate, nameServers, status, and whoisServer_**.
- **_INVALID_TLD_** - This case is for incorrect entries like: example.example. We would ignore these domains.
- **_UNSUPPORTED_TLD_** - This case is for unsupported TLDs, please refer to: [https://knowledge.whoisxmlapi.com/are-there-any-tlds-that-you-dont-support](https://knowledge.whoisxmlapi.com/are-there-any-tlds-that-you-dont-support).

```

--------------------------------

### cURL request with JSON body

Source: https://whois.whoisxmlapi.com/documentation/making-requests

Sends a POST request to the WhoisXML API with a JSON body containing the domain name and API key. Replace 'API_KEY' with your personal API key.

```bash
curl --location 'https://www.whoisxmlapi.com/whoisserver/WhoisService' \
    --header 'Content-Type: application/json' \
    --data '{
        "domainName": "google.com",
        "apiKey": "API_KEY"
    }'
```

--------------------------------

### WHOIS API Response Fields

Source: https://whois.whoisxmlapi.com/documentation/output

A structured list of all output parameters returned by the WHOIS API when querying domain information.

```APIDOC
## WHOIS API Response Fields

### Description
This section documents the output parameters returned by the WHOIS API for a domain lookup. Each field provides specific information about the domain, its contacts, name servers, and registration details.

### Output Parameters

| Field | Description |
|-------|-------------|
| registrant.rawText | Registrant contact information raw text |
| registrant.unparsable | The part of the registrant contact block that could not be parsed. |
| administrativeContact | The administrative contact is the person in charge of the administrative dealings pertaining to the company owning the domain name. Fields are the same as for the **_registrant_** field. |
| technicalContact | The technical contact is the person in charge of all technical questions regarding a particular domain name. Fields are the same as for the **_registrant_** field. |
| billingContact | The billing contact for the domain name. Fields are the same as for the **_registrant_** field. |
| zoneContact | The DNS zone contact for the domain name. Fields are the same as for the **_registrant_** field. |
| domainName | Target domain name. |
| domainNameExt | The domain name extension. |
| nameServers | A name server is a computer server that hosts a network service for providing responses to queries against a directory service. |
| nameServers.rawText | The raw text of the name server records. |
| nameServers.hostNames | Array of name server host names. |
| nameServers.ips | Array of name server IP addresses. |
| status | Array of statuses. See [https://www.icann.org/resources/pages/epp-status-codes-2014-06-16-en](https://www.icann.org/resources/pages/epp-status-codes-2014-06-16-en) |
| registrarName | The name of the registrar. |
| registrarIANAID | The registrar ID assigned by ICANN. |
| whoisServer | The WHOIS or RDAP server that returned the record. |
| contactEmail | The best available contact email for this domain name. |
| estimatedDomainAge | Estimated domain age in days. |
| ips | Array of IP addresses associated with the domain name. |
| domainAvailability | Domain availability indicates if the domain name is available to be registered. It is always returned with a full verdict — one of _AVAILABLE_, _UNAVAILABLE_, or _UNDETERMINED_ — computed from the WHOIS or RDAP record. IP lookups return this field empty. |
| rawText | The complete raw text of the WHOIS or RDAP record. |
| strippedText | The stripped text of the WHOIS or RDAP record includes part of the raw excluding header and footer, this should only include identifiable fields. |
| header | The header of the WHOIS or RDAP record is part of the raw text up until the first identifiable field. |
| footer | The footer of the WHOIS or RDAP record is part of the raw after the last identifiable field. |
| parseCode | The field is used for internal diagnostics. |
| customField1Name | RegistrarContactEmail |
| customField1Value | The value for customField1Name. |
| customField2Name | RegistrarContactPhone |
| customField2Value | The value for customField2Name. |
| customField3Name | RegistrarURL |
| customField3Value | The value for customField3Name. |
| audit | Record collection metadata. |
| audit.createdDate | The date (UTC) when the WHOIS or RDAP record was first collected. |
| audit.updatedDate | The date (UTC) when the WHOIS or RDAP record was last updated. |
| dataError | The error code indicating an error in this WHOIS or RDAP record. Possible values are: |
```

--------------------------------

### GET_DN_AVAILABILITY Response

Source: https://whois.whoisxmlapi.com/documentation/output

When the request sets cmd=GET_DN_AVAILABILITY, the full WHOIS record is replaced by a compact DomainInfo object containing only the domain availability verdict and the domain name. The response can be in JSON or XML format.

```APIDOC
## GET_DN_AVAILABILITY Response

### Description
When the request sets `cmd=GET_DN_AVAILABILITY`, the full WHOIS record is replaced by a compact `DomainInfo` object carrying only the availability verdict and the domain name.

### Response Format
JSON or XML

### Response Example (JSON)
```json
{
    "DomainInfo": {
        "domainAvailability": "UNAVAILABLE",
        "domainName": "google.com"
    }
}
```

### Response Example (XML)
```xml
<?xml version="1.0" encoding="UTF-8"?>
<DomainInfo>
    <domainAvailability>UNAVAILABLE</domainAvailability>
    <domainName>google.com</domainName>
</DomainInfo>
```

### Response Fields
- **DomainInfo** (object) - Contains the domain availability information.
  - **domainAvailability** (string) - The availability verdict, e.g., "UNAVAILABLE".
  - **domainName** (string) - The queried domain name, e.g., "google.com".

### Output Schema
- JSON Schema (draft-07):
  - [WHOIS record schema](https://whois.whoisxmlapi.com/documentation/whois-api/whois-record.schema.json)
  - [DomainInfo schema](https://whois.whoisxmlapi.com/documentation/whois-api/domain-info.schema.json)
  - [Error schema](https://whois.whoisxmlapi.com/documentation/whois-api/error.schema.json)
- XML Schema (XSD):
  - [WHOIS record XML schema](https://whois.whoisxmlapi.com/documentation/whois-api/whois-record.xsd)
  - [DomainInfo XML schema](https://whois.whoisxmlapi.com/documentation/whois-api/domain-info.xsd)
  - [Error XML schema](https://whois.whoisxmlapi.com/documentation/whois-api/error.xsd)
```

--------------------------------

### Error Codes

Source: https://whois.whoisxmlapi.com/documentation/error-handling

Lists the error codes returned by the WHOIS API, including their HTTP status and description.

```APIDOC
## Error Codes

### Description
Common error codes returned by the WHOIS API.

### Error Codes Table
| Error Code | HTTP Status | Description |
|------------|-------------|-------------|
| WHOIS_01 | 200 | Validation error message, e.g. mutually exclusive cache flags: preferFresh and _hardRefresh cannot be used together. |
| WHOIS_03 | 200 | Unable to retrieve whois record. |
| AUTHENTICATE_04 | 401 | API key required (Authorization: Bearer key or apiKey field). |
| WHOIS_02 | 401 | unknown user. |
| AUTHENTICATE_05 | 401 | no active subscription / no credits remaining. |
| AUTHENTICATE_10 | 403 | Your IP address is not added to the IP allowlist (https://user.whoisxmlapi.com/settings/ip-allow-list). The request is rejected. |
| AUTHENTICATE_06 | 429 | rate limit exceeded (also sends a Retry-After header, see Limits). |
| WHOIS_01 | 500 | 503 | Internal server error. |
```

--------------------------------

### WHOIS API Custom Fields

Source: https://whois.whoisxmlapi.com/documentation/output

Explains the custom fields (customFieldN) returned in WHOIS/RDAP responses, which carry registrar contact details for domains and network-registration fields for IPs.

```APIDOC
## WHOIS API Custom Fields

### Description
This section describes the custom fields (customFieldN) that are returned in WHOIS/RDAP responses. The three customFieldN slots hold different data depending on the lookup type.

### Custom Fields

- For a domain, the custom fields carry the registrar contact details in fixed positions:
  - _customField1Name_ is _RegistrarContactEmail_
  - _customField2Name_ is _RegistrarContactPhone_
  - _customField3Name_ is _RegistrarURL_
- For an IP, the custom fields carry network-registration fields such as _NetHandle_, _NetRange_, _CIDR_, _NetName_, _OriginAS_, and _OwnerID_, assigned in order rather than to fixed positions.
- Only three slots are available, so read _customFieldNName_ to identify each field; any additional fields are omitted.

```

--------------------------------

### Error Response Format

Source: https://whois.whoisxmlapi.com/documentation/error-handling

Shows the structure of an error response in JSON and XML formats.

```APIDOC
## Error Response Format

### Description
On an error, the response body carries an ErrorMessage object with an errorCode and a human-readable msg. In JSON the object is wrapped under an ErrorMessage key; in XML it is returned as a document rooted at <ErrorMessage>.

### Response
#### Error Response
- **ErrorMessage** (object) - Contains error details.
  - **errorCode** (string) - The error code.
  - **msg** (string) - Human-readable error message.

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

#### Example (XML)
<?xml version="1.0" encoding="UTF-8"?>
<ErrorMessage>
    <errorCode>WHOIS_01</errorCode>
    <msg>mutually exclusive cache flags: preferFresh and _hardRefresh cannot be used together</msg>
</ErrorMessage>
```

--------------------------------

### WHOIS API Error Responses

Source: https://whois.whoisxmlapi.com/documentation/error-handling

This section documents the error responses returned by the WHOIS API. Each error includes an HTTP status code, an error code, and a message. The response body is available in both JSON and XML formats.

```APIDOC
## WHOIS API Error Responses

### Description
This section describes the error responses returned by the WHOIS API. Each error includes an HTTP status code, an error code, and a message. The response body is available in both JSON and XML formats.

### Error Responses

#### 200 — Validation error
- **errorCode** (string) - WHOIS_01
- **msg** (string) - mutually exclusive cache flags: preferFresh and _hardRefresh cannot be used together

#### 200 — Unable to retrieve WHOIS record
- **errorCode** (string) - WHOIS_03
- **msg** (string) - Unable to retrieve whois record

#### 401 — Missing API key
- **errorCode** (string) - AUTHENTICATE_04
- **msg** (string) - API key required (Authorization: Bearer key or apiKey field)

#### 401 — Unknown user
- **errorCode** (string) - WHOIS_02
- **msg** (string) - unknown user

#### 401 — No subscription / no credits remaining
- **errorCode** (string) - AUTHENTICATE_05
- **msg** (string) - no credits remaining

#### 403 — IP not on allowlist
- **errorCode** (string) - AUTHENTICATE_10
- **msg** (string) - 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)
- **errorCode** (string) - AUTHENTICATE_06
- **msg** (string) - rate limit exceeded

#### 5xx — Server error
- **errorCode** (string) - WHOIS_01
- **msg** (string) - Internal server error

### Response Example (JSON)
```json
{
    "ErrorMessage": {
        "errorCode": "WHOIS_01",
        "msg": "mutually exclusive cache flags: preferFresh and _hardRefresh cannot be used together"
    }
}
```

### Response Example (XML)
```xml
<?xml version="1.0" encoding="UTF-8"?>
<ErrorMessage>
    <errorCode>WHOIS_01</errorCode>
    <msg>mutually exclusive cache flags: preferFresh and _hardRefresh cannot be used together</msg>
</ErrorMessage>
```

### Additional Information
The error body is described by the [error JSON Schema](https://whois.whoisxmlapi.com/documentation/whois-api/error.schema.json) and the [error XSD](https://whois.whoisxmlapi.com/documentation/whois-api/error.xsd).
```
Tokens:
Raw