Handle rate limits

Overview

The Domains API enforces a per-credential, windowed rate limit. The RateLimit-Remaining header on every response shows how many requests remain in the current window. When it reaches 0, the next request returns HTTP 429 with no response body. The limit applies per credential regardless of which endpoint you call.

Rate limit response headers

The following headers are included on every response to a rate-limited route — not just 429s — so your client can track current usage without waiting for a rejection.

Example 429 response:

HTTP/2 429
ratelimit-limit: 600
ratelimit-remaining: 0
ratelimit-reset: 1399

Handling 429 in code

Read RateLimit-Reset to know how long to wait before retrying. For long-running clients, add exponential backoff with jitter on top of the server-suggested wait. The following is an example of how to do this in JavaScript:

async function callWithRetry(url, headers, attempts = 5) {
  for (let attempt = 0; attempt < attempts; attempt++) {
    const res = await fetch(url, { headers });
    if (res.status !== 429) return res;

    const resetSec = parseInt(res.headers.get("ratelimit-reset") ?? "30", 10);
    const jitter = Math.floor(Math.random() * 1000);
    await new Promise((r) => setTimeout(r, resetSec * 1000 + jitter));
  }
  throw new Error("Rate limit retries exhausted");
}

Strategies to stay under the limit

To avoid hitting the limit, apply one or more of the following strategies:

• Use bulk operations where they exist. For single-domain availability checks, use GET /v3/domains/check-availability (preferred). For bulk availability, POST /v1/domains/available accepts an array of names — one request can replace dozens of single-domain calls.
• Cache availability results when appropriate (v1 only). The definitive field on DomainAvailableResponse indicates whether the answer came from a live registry call or a cached one. Cache definitive: false results briefly client-side for repeat lookups.
• Use cursor pagination, not parallel page-walks. Go to Pagination for more information.
• Spread bursts across credentials only when each credential maps to a distinct logical caller. Sharing one credential across many hosts and counting on the limit being per-credential is fragile — limits can be tightened to per-account at any time.

Higher limits

If you have a use case that legitimately needs higher limits than those currently enforced, contact the developer support channel. Document the use case, expected sustained rate, and bursts.

Additional information

Go to Retry semantics for full retry guidance.

Last updated on