WHOIS API Rate Limits: How to Handle 429 Errors and Retries

Introduction

A single WHOIS API request is easy: send a domain name, authenticate the request, parse the JSON response, and move on. Production workloads are different. A SaaS onboarding flow, domain intelligence pipeline, cybersecurity investigation, or portfolio audit may need to process hundreds or thousands of domains while preserving correctness.

The hard part is not calling the WHOIS API. The hard part is handling limits and partial failure safely: HTTP 429 errors, request timeouts, transient 5xx responses, network interruptions, duplicate inputs, and jobs that need to resume after a process restart.

HTTP 429 errors are normal in API integrations. They should not be treated as WHOIS data errors. A 429 response does not mean a domain is unavailable, unregistered, invalid, or missing. It means your client should slow down and retry later with a controlled backoff strategy.

Looking for High-Volume WHOIS Lookups?

Why WHOIS APIs Have Rate Limits

Rate limits are not just a billing mechanism. They protect the API provider, upstream registry systems, and your own production application from uncontrolled traffic patterns.

• Registry constraints. WHOIS and RDAP data may depend on upstream registries with their own latency, throttling and availability characteristics.
• Abuse prevention. Domain data endpoints can be attractive targets for scraping and credential abuse. Limits reduce the blast radius.
• Fair usage. Predictable quotas help multiple customers share infrastructure without one noisy client degrading everyone else.
• Infrastructure protection. Rate controls prevent accidental bursts from overwhelming queues, caches or upstream connectors.
• Service reliability. A known ceiling gives developers something concrete to design around.

Good production code treats rate limits as part of the API contract. It measures usage, avoids uncontrolled concurrency, and stores partial results when a run cannot finish in one pass.

What HTTP 429 Means

HTTP429 Too Many Requests means the client has exceeded a usage or rate limit. The WhoisJSON API documentation also documents theRemaining-Requests response header, which reports the number of API calls left in the current billing period.

A WHOIS API 429 error is not a domain result. It does not mean the domain is unavailable. It does not mean the domain was not found. It means the request should usually be retried later, after a delay, with backoff logic.

Common Mistakes in WHOIS API Integrations

Most production problems come from mixing transport failures with domain data. A request failure is a property of the API call. A registered, expired, unavailable or privacy-protected domain is a data result. Keep those states separate.

• Sending uncontrolled bursts of requests.
• Retrying immediately after a 429 response.
• Treating a timeout as "domain not found".
• Ignoring HTTP status codes and only parsing response bodies.
• Not setting explicit request timeouts.
• Not deduplicating domains before lookup.
• Not logging failed or unknown results separately.
• Allowing infinite retries that never settle.
• Mixing unavailable, unknown and error states in the same field.

Which Errors Should Be Retried?

Retry only failures that are likely to become successful later. Invalid input and invalid authentication should fail fast so the underlying issue is visible.

Exponential Backoff and Jitter

Exponential backoff increases the wait time after each failed attempt. Jitter adds a small random delay so that many workers do not retry at exactly the same time. A maximum retry count prevents a bad input or persistent outage from blocking the queue forever.

A simple formula:

delay = baseDelay * 2^attempt + randomJitter

After the final retry, mark the result as unknown or retryable_error rather than inventing a WHOIS result. This is important for downstream systems: an unknown lookup can be retried later, while a valid WHOIS response can be used for decisions.

Recommended Production Architecture

For simple scripts, sequential processing may be enough. For production, a queue is safer because it separates job intake from API execution and lets you resume failed work.

1. Normalize input domains.
2. Deduplicate the list.
3. Validate domain format.
4. Push jobs into a queue.
5. Process with workers.
6. Apply rate limits.
7. Retry 429 errors and timeouts with backoff.
8. Store success, unavailable/taken and unknown/error separately.
9. Log API status codes.
10. Monitor quota usage.

The most important design choice is to make failure explicit. A domain can be registered, unregistered, expired, privacy-protected, or malformed. Separately, a request can fail, time out, or hit a rate limit. Those categories should not collapse into one boolean.

Python Example: Retry WHOIS Requests Safely

This example uses requests, a 10-second timeout, a maximum retry count, exponential backoff with jitter, and explicit handling for retryable versus non-retryable status codes.

import random
import time
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://whoisjson.com/api/v1"
RETRYABLE_STATUS = {429, 500, 502, 503, 504}

def backoff_delay(attempt, base_delay=1.0, max_delay=30.0):
    jitter = random.uniform(0, 0.5)
    return min(base_delay * (2 ** attempt) + jitter, max_delay)

def lookup_whois(domain, max_retries=3):
    url = f"{BASE_URL}/whois"
    headers = {"Authorization": f"TOKEN={API_KEY}"}
    params = {"domain": domain}

    for attempt in range(max_retries + 1):
        try:
            response = requests.get(
                url,
                headers=headers,
                params=params,
                timeout=10,
            )

            if response.status_code == 200:
                return {
                    "domain": domain,
                    "status": "success",
                    "data": response.json(),
                }

            if response.status_code in (400, 401, 403):
                return {
                    "domain": domain,
                    "status": "failed",
                    "error": f"HTTP {response.status_code}: {response.text}",
                }

            if response.status_code in RETRYABLE_STATUS:
                if attempt < max_retries:
                    time.sleep(backoff_delay(attempt))
                    continue
                return {
                    "domain": domain,
                    "status": "retryable_error",
                    "error": f"HTTP {response.status_code} after retries",
                }

            return {
                "domain": domain,
                "status": "failed",
                "error": f"Unexpected HTTP {response.status_code}",
            }

        except requests.Timeout:
            if attempt < max_retries:
                time.sleep(backoff_delay(attempt))
                continue
            return {
                "domain": domain,
                "status": "retryable_error",
                "error": "timeout after retries",
            }
        except requests.RequestException as exc:
            if attempt < max_retries:
                time.sleep(backoff_delay(attempt))
                continue
            return {
                "domain": domain,
                "status": "retryable_error",
                "error": str(exc),
            }

print(lookup_whois("example.com"))

Node.js Example: Handle 429 Errors and Timeouts

Node.js 18 and newer include native fetch. This example uses AbortController for timeouts and retries 429 and 5xx responses with jittered exponential backoff.

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://whoisjson.com/api/v1';
const RETRYABLE_STATUS = new Set([429, 500, 502, 503, 504]);

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

function backoffDelay(attempt, baseDelay = 1000, maxDelay = 30000) {
  const jitter = Math.floor(Math.random() * 500);
  return Math.min(baseDelay * (2 ** attempt) + jitter, maxDelay);
}

async function fetchWithTimeout(url, options = {}, timeoutMs = 10000) {
  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), timeoutMs);

  try {
    return await fetch(url, {
      ...options,
      signal: controller.signal,
    });
  } finally {
    clearTimeout(timeout);
  }
}

async function lookupWhois(domain, maxRetries = 3) {
  const url = `${BASE_URL}/whois?domain=${encodeURIComponent(domain)}`;

  for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
    try {
      const response = await fetchWithTimeout(url, {
        headers: { Authorization: `TOKEN=${API_KEY}` },
      });

      if (response.status === 200) {
        return {
          domain,
          status: 'success',
          data: await response.json(),
        };
      }

      if ([400, 401, 403].includes(response.status)) {
        return {
          domain,
          status: 'failed',
          error: `HTTP ${response.status}: ${await response.text()}`,
        };
      }

      if (RETRYABLE_STATUS.has(response.status)) {
        if (attempt < maxRetries) {
          await sleep(backoffDelay(attempt));
          continue;
        }
        return {
          domain,
          status: 'retryable_error',
          error: `HTTP ${response.status} after retries`,
        };
      }

      return {
        domain,
        status: 'failed',
        error: `Unexpected HTTP ${response.status}`,
      };
    } catch (error) {
      if (attempt < maxRetries) {
        await sleep(backoffDelay(attempt));
        continue;
      }
      return {
        domain,
        status: 'retryable_error',
        error: error.name === 'AbortError' ? 'timeout after retries' : error.message,
      };
    }
  }
}

console.log(await lookupWhois('example.com'));

Processing Multiple Domains Safely

When you process a list of domains, the first optimization is not concurrency. It is avoiding unnecessary calls. Normalize domains, remove protocols and paths, lowercase where appropriate, and deduplicate the list before calling the API.

For small lists, sequential processing is often enough and easier to debug. For larger lists, use controlled concurrency: a fixed number of workers pulling from a queue, each respecting your API plan and retry policy. Do not fire 10,000 requests at once and hope the runtime, network and API all absorb the burst.

• Deduplicate domains before lookup.
• Process sequentially for small lists.
• Use controlled concurrency for larger lists.
• Store partial results as each request completes.
• Resume failed jobs instead of restarting the whole batch.
• Export unknown results for retry later.

For high-volume workflows, review the Bulk WHOIS API product page and compare plan capacity on API pricing. This article stays focused on engineering reliability: rate limits, retries, backoff and safe failure states.

When to Upgrade Your API Plan

Free plans are useful for testing, prototypes and small internal tools. WhoisJSON includes 1,000 free requests per month according to the API documentation, and the Free Domain API page explains the free developer access.

Production workloads need predictable quota and rate behavior. Consider upgrading when queue delays become too high, when retries start piling up, or when your daily volume approaches your plan capacity. Estimate volume from domains per day, checks per domain, retry rate, and how quickly results must be available.

Use API pricing to choose a plan that matches the workload before rate-limit handling becomes the bottleneck.

WHOIS API Rate Limit Checklist

• Validate domains before calling the API.
• Deduplicate inputs.
• Set explicit timeouts.
• Distinguish 400, 401, 429 and 5xx.
• Retry only retryable failures.
• Use exponential backoff.
• Add jitter.
• Cap max retries.
• Store unknown results separately.
• Monitor quota usage.
• Avoid uncontrolled concurrency.
• Test with a small batch first.

FAQ

Conclusion

WHOIS API rate limits are normal. HTTP 429 is not a WHOIS data result, and a timeout is not a domain state. Production workflows need explicit timeouts, retry policies, exponential backoff, jitter, bounded retries and a clear separation between valid data and unknown/error states.

Avoid uncontrolled request bursts. Store partial results. Monitor status codes and remaining quota. Keep failed lookups separate from valid WHOIS responses so downstream systems do not make decisions from unreliable data.