API Rate Limiting

Every WhoisFreaks API enforces a per-minute request limit that protects platform stability and keeps response times fast for everyone. This guide explains how those limits work, how they differ across plans and endpoints, and how to read the rate limit data we return on every response, so you never have to guess.

Measured in requests/minuteWindow resets every minuteHeaders on every responseHTTP 429 when exceeded

Overview

Rate limiting controls how many API requests you can make within a one-minute window. It is separate from your API credits; credits are your overall query quota, while the rate limit governs how quickly you may spend them. A request that is throttled by the rate limit does not consume a credit.

Two things determine your limit:

Factor

What it means

Your plan

Larger plans are allotted more requests per minute. Enterprise plans receive fully customized limits.

The endpoint category

Lightweight live lookups get a higher limit than heavier bulk, historical, and reverse queries.

ⓘ Tip

You do not need to count requests yourself. Every API response includes a set of rate limit headers that tell you your limit, how many requests remain, and when the window resets. Read those headers instead of tracking usage on your end.

How rate limiting works

Limits are expressed in requests per minute (RPM). Each request you make within the current minute decrements your remaining allowance. When the window resets, your full allowance is restored.

If you send more requests than your plan permits for a given endpoint category within that window, the API stops fulfilling further requests and responds with HTTP status 429 Too Many Requests until the window resets. To know exactly when that happens, read the x-ratelimit-remaining-time header, which reports the time left until your limit is fully restored.

Because the limit is enforced per endpoint category rather than as one shared pool, spending your live-lookup allowance does not reduce what is available for bulk or historical queries, and vice versa.

Rate limit headers

Every response from a rate-limited endpoint, including both successful responses and 429 responses, carries three headers describing your current rate limit state. Read these to make informed decisions about pacing your requests.

Headers

Description

x-ratelimit-allowed-requestsInteger

The total number of requests allowed per minute for your plan, for the category the endpoint belongs to. This is your ceiling for the current window.

x-ratelimit-remaining-requestsInteger

How many requests you have left in the current window before you hit the limit. When this reaches 0, further requests are throttled with a 429 until the window resets.

x-ratelimit-remaining-timeNanoseconds

The time remaining until your rate limit is fully reset and your allowance is restored. Unit: nanoseconds · divide by 1,000,000,000 for seconds

Example response headers

A successful request that still has headroom returns headers like these:

200 OK · response headers

HTTP/1.1 
200 OK
content-type: application/json
x-ratelimit-allowed-requests: 80
x-ratelimit-remaining-requests: 79
x-ratelimit-remaining-time: 58273000000

In this example the plan allows 80 live requests per minute, 79 remain in the current window, and the window fully resets in 58,273,000,000 nanoseconds, which is about 58.3 seconds.

Reading the reset time

ⓘ Tip

The x-ratelimit-remaining-time value is in nanoseconds, not seconds. This is a common source of confusion. Always convert before using it for delays or display.

Use these conversions, where n is the raw header value:

Target unit

Conversion

Example (n = 58,273,000,000)

Milliseconds

n / 1,000,000

58,273 ms

Seconds

n / 1,000,000,000

58.273 s

Handling 429 responses

When you exceed your limit, the API responds with 429 Too Many Requests. The same rate limit headers are still present, so you can read x-ratelimit-remaining-time to know exactly how long to wait before retrying.

429 Too Many Requests · response headers

HTTP/1.1 429 Too Many Requests
content-type: application/json
x-ratelimit-allowed-requests: 80
x-ratelimit-remaining-requests: 0
x-ratelimit-remaining-time: 41822000000

Here, remaining-requests is 0 and the limit resets in about 41.8 seconds. The correct response is to pause new requests until that time has elapsed, then resume.

ⓘ Warning

Recommended pattern: on a 429, sleep for the converted remaining-time (plus a small buffer of 100–250 ms to account for clock differences), then retry. Avoid tight retry loops that hammer the API while still limited.

Best practices

A few habits keep your integration smooth and avoid unnecessary 429 responses.

Practice

Why it helps

Read the headers, don't count client-side

The headers are authoritative. Tracking usage yourself risks drift and double-counting across processes or machines.

Throttle before you hit zero

Watch remaining-requests and slow down as it approaches the limit, rather than waiting for a 429.

Back off using the reset time

On a 429, sleep for the converted remaining-time plus a small buffer instead of retrying immediately.

Spread requests evenly

Pacing requests across the minute avoids bursts that exhaust the window in the first few seconds.

Cache where you can

WHOIS, DNS, and similar records change slowly. Caching results reduces repeat calls and conserves both rate and credits.

Match the endpoint to the job

Use bulk endpoints for many lookups at once rather than firing many single live requests in a loop.

If your workload consistently needs more throughput than your plan allows, upgrading to a larger plan raises your RPM, and Enterprise plans offer a fully customized limit.

FAQs

Common questions about API rate limiting, headers, and 429 responses.

−

Do I need to track my request count myself?

No. Every response includes the x-ratelimit-allowed-requests, x-ratelimit-remaining-requests, and x-ratelimit-remaining-time headers. Read them to see your limit, what remains, and when it resets, rather than maintaining your own counter.

What unit is x-ratelimit-remaining-time in?

Nanoseconds. Divide by 1,000,000,000 to get seconds, or by 1,000,000 to get milliseconds. The reset time section lays out the conversions.

What happens when I exceed the limit?

The API responds with HTTP 429 Too Many Requests and stops fulfilling further requests until the window resets. The rate limit headers are still included, so you can read x-ratelimit-remaining-time to know how long to wait. Throttled requests do not consume API credits.

Why do different endpoints have different limits?

Endpoints fall into three categories with different processing costs. Lightweight live lookups get the highest RPM, bulk endpoints a medium limit, and historical and reverse queries the lowest, since they scan far more data per request.

Is the rate limit the same as my API credits?

No. They are two separate controls. API credits are your total query quota over the life of your plan or billing period. The rate limit caps how many requests you can make per minute. You can have plenty of credits left and still be rate limited if you send requests too quickly.

Do unused requests roll over to the next minute?

No. The allowance applies to a single one-minute window. When the window resets, your full per-minute allowance is restored regardless of how many requests you used in the previous minute.

How do I get a higher rate limit?

Move to a larger plan for a higher RPM across all categories, or contact our team for an Enterprise plan with a fully customized requests-per-minute limit built around your needs. See current options on the pricing page.