Lookups and Monitors API Error Codes

The Lookups and Monitors APIs use standard HTTP status codes to indicate the success or failure of requests. Understanding these codes helps you handle errors gracefully and troubleshoot issues effectively.

Status Codes

Status Code	Description
200	OK - The request was successful.
206	Partial Content - The request was partially successful. Some data is unavailable but the request returned what was available. This typically occurs when backend services are temporarily unavailable or when data for some requested items cannot be retrieved.
400	Bad Request - The request is malformed or contains invalid parameters. Check the error message for details about what needs to be corrected.
401	Unauthorized - Authentication credentials are missing, invalid, or expired. Verify your API key and authentication method.
403	Forbidden - The authenticated account does not have permission to access this resource or endpoint. This may indicate insufficient subscription level or access rights.
404	Not Found - The requested resource does not exist. This may occur when querying for a domain that has never been registered or for data that is not available in our systems.
500	Internal Server Error - An unexpected error occurred on the server. If this persists, contact DomainTools support at enterprisesupport@domaintools.com.
503	Service Unavailable - The service is temporarily unavailable, typically due to maintenance or high load. Implement exponential backoff and retry the request.

Error Response Format

Error responses follow a consistent JSON structure:

{
  "error": {
    "code": 400,
    "message": "Invalid domain name format"
  }
}

Common Error Scenarios

Authentication Errors (401)

Cause: Missing or invalid API credentials.

Solutions:

• Verify your API key is correct
• Check that your authentication method (header, HMAC, or basic auth) is properly configured
• Ensure your API key hasn’t expired

Authorization Errors (403)

Cause: Insufficient permissions or subscription level.

Solutions:

• Verify your account has access to the requested endpoint
• Check your subscription includes the API product you’re trying to use
• Contact your account manager if you need additional access

Not Found Errors (404)

Cause: Requested resource doesn’t exist.

Common scenarios:

• Querying a domain that has never been registered
• Requesting historical data that predates our records
• Using an invalid endpoint path

Rate Limiting (503)

Cause: Too many requests in a short time period.

Solutions:

• Implement exponential backoff retry logic
• Check your rate limits using the Account Information endpoint
• Distribute requests over time rather than in bursts
• Consider upgrading your subscription for higher rate limits

Best Practices

1. Always check status codes: Don’t assume success - verify the response status code
2. Parse error messages: Error messages contain specific details about what went wrong
3. Implement retry logic: Use exponential backoff for 500 and 503 errors
4. Log errors: Keep detailed logs of errors for troubleshooting
5. Monitor rate limits: Track your API usage to avoid hitting limits

Lookups and Monitors Specific Notes

Exception: Reverse IP WHOIS

The Reverse IP WHOIS endpoint does not return 403 (Forbidden) errors. It uses all other standard error codes.

Some endpoints may return additional context in their error messages:

Exception: Parsed WHOIS

When parsing fails, the API returns a 206 (Partial Content) status with the raw WHOIS record but without parsed data. The error response includes:

{
  "error": {
    "code": 206,
    "message": "We were NOT able to parse the WHOIS record"
  }
}

This allows you to still access the raw WHOIS data even when automated parsing fails.

Exception: Domain History

When troubleshooting Domain History requests, you may encounter:

• 401 errors: Verify your authentication credentials are correct
• 429 errors: You’ve exceeded rate limits - implement exponential backoff

While not in the standard error code list, the Domain History endpoint may return 429 errors when rate limits are exceeded. Implement exponential backoff when encountering this error.

Rate Limiting

To check your current rate limits and usage, use the Account Information endpoint.

Getting Help

If you encounter persistent errors or need assistance:

• Review the API Reference for endpoint-specific details
• Download the OpenAPI specification for use with code generation and API tooling
• Contact support at enterprisesupport@domaintools.com