--- title: "API Rate Limiting - WhoisFreaks" slug: "/documentation/api-rate-limiting" description: "Every WhoisFreaks API enforces a per-minute request limit that protects platform stability and keeps response times fast. Learn how rate limits work, headers, and best practices." --- # API Rate Limiting Keep your integration fast and reliable. Learn how request limits work, read rate limit headers, and handle 429 responses the right way. ## 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](https://whoisfreaks.com/documentation/api-rate-limiting#handling-429-responses) 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](https://whoisfreaks.com/contact). ### 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**](https://whoisfreaks.com/documentation/api-rate-limiting#reading-the-reset-time) 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**](https://whoisfreaks.com/contact) for an Enterprise plan with a fully customized requests-per-minute limit built around your needs. See current options on the [**pricing page**](https://whoisfreaks.com/pricing).