Platform
Rate limits
In short
Each account gets a fixed number of requests per rolling 60 second window, 30 on the free plan, 300 once you have bought credits, 600 with a monthly or yearly subscription, and 5 per IP without a key. Every response carries X-RateLimit headers, and a 429 tells you exactly how many seconds to wait. Verify lists with bulk jobs, which count as one request for up to 100,000 addresses.
On this page
Rate limits keep the API fast for everyone. They count requests, not addresses, so the right endpoint choice matters more than the number itself.
Limits by plan#
Limits apply per rolling 60 second window. The plan is detected automatically from your account.
| Plan | Requests per minute | Who is on it |
|---|---|---|
| Free | 30 | Accounts that have not bought credits yet |
| Trial | 30 | Accounts on a trial |
| Pay as you go | 300 | Accounts that have bought credits at least once |
| Pro | 600 | Accounts with an active monthly or yearly subscription |
| Anonymous | 5 per IP address | Requests without an API key, such as sandbox calls |
The window slides: each request counts for exactly 60 seconds after it was made, so there is no burst at the top of the minute.
How requests are counted#
Every authenticated request counts against one bucket, chosen by the credential:
| Credential | Bucket | Limit |
|---|---|---|
Personal API key (rv_live_, rv_test_) | Your account | Your plan, or the key's override |
| OAuth token for a personal account | That account | The account's plan |
| Organization API key | The organization | The organization's limit, or the owner's plan when none is set |
| OAuth token for an organization | The organization | The organization's limit |
| No key | The caller's IP address | 5 per minute |
All the personal keys on one account share its bucket, so splitting traffic across keys does not raise the limit. Keys with their own limit (see below) count in a separate bucket at that limit. Organization traffic has its own bucket, separate from every member's personal keys.
Rate limit headers#
Every response carries the state of your bucket:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed per 60 seconds for this bucket |
X-RateLimit-Remaining | Requests left in the current window |
X-RateLimit-Reset | Unix time (seconds) when the oldest request in the window expires |
Retry-After | On 429 only: seconds to wait before the next request |
HTTP/2 200
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1762854157Check your current limit#
GET /rate-limit returns the limit that applies to your key, where it comes from and how much of it is used. It counts as one request.
curl https://api.rocketverifier.com/rate-limit \
-H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"{
"success": true,
"tier": "payg",
"subscription_type": "free",
"limit_source": "plan",
"limit": 300,
"remaining": 287,
"used": 13,
"reset_at": 1762854157
}limit_source is plan when the plan tier applies and api_key when the key has its own limit.
Per-key and organization limits#
A key can carry its own requests-per-minute limit that replaces the plan tier, higher or lower. Organizations can carry one limit for all their keys, and a single organization key can override it. These limits are set by our team: email support@rocketverifier.com with the key or organization and the volume you need.
Lower limits are useful too: cap a batch import key at a low rate so it never crowds out your signup traffic.
Endpoint limits#
A few endpoints have an extra limit on top of your plan:
| Endpoint | Extra limit |
|---|---|
POST /v1/finder | 20 requests and 40 mailbox checks per minute per account |
POST /v1/tools/verify-free | 2 lookups per IP per day (429 daily_limit_reached) |
Handle 429 responses#
A 429 means the bucket is full. Wait the number of seconds in Retry-After, then send the same request again.
{
"error": {
"code": "rate_limited",
"message": "Rate limit exceeded. Please try again later.",
"details": {
"limit": 300,
"reset_at": "2026-11-11T09:42:37+00:00",
"retry_after_seconds": 12
}
}
}The SDKs do this for you: they wait Retry-After and retry up to 3 times with the same idempotency key. With plain HTTP, wrap your calls:
async function withRateLimit(send, maxAttempts = 5) {
for (let attempt = 1; ; attempt++) {
const res = await send();
if (res.status !== 429 || attempt === maxAttempts) return res;
const wait = Number(res.headers.get("Retry-After")) || 2 ** attempt;
await new Promise((r) => setTimeout(r, wait * 1000 + Math.random() * 250));
}
}
const idempotencyKey = crypto.randomUUID();
const res = await withRateLimit(() =>
fetch("https://api.rocketverifier.com/v1/verify", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.ROCKETVERIFIER_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": idempotencyKey,
},
body: JSON.stringify({ email: "maya@northwind.io" }),
})
);import os
import random
import time
import uuid
import requests
def with_rate_limit(send, max_attempts: int = 5) -> requests.Response:
for attempt in range(1, max_attempts + 1):
res = send()
if res.status_code != 429 or attempt == max_attempts:
return res
wait = int(res.headers.get("Retry-After") or 2**attempt)
time.sleep(wait + random.random() / 4)
return res
idempotency_key = str(uuid.uuid4())
res = with_rate_limit(
lambda: requests.post(
"https://api.rocketverifier.com/v1/verify",
headers={
"Authorization": f"Bearer {os.environ['ROCKETVERIFIER_API_KEY']}",
"Idempotency-Key": idempotency_key,
},
json={"email": "maya@northwind.io"},
timeout=35,
)
)To avoid 429s in the first place, pace requests from X-RateLimit-Remaining: when it drops near zero, pause until X-RateLimit-Reset.
Bulk or single requests#
Pick the endpoint by how the addresses arrive, not by how many you have.
| Situation | Use | Requests used |
|---|---|---|
| One address at a time, a person is waiting (signup, checkout) | POST /v1/verify | 1 per address |
| A list you already have, up to 100,000 addresses | POST /v1/verify/bulk | 1 per job |
| A CSV, TSV, TXT or XLSX file, up to 500,000 addresses | POST /v1/verify/bulk/upload | 1 per job |
| Waiting for a job to finish | A job.completed webhook | 0 |
Looping over POST /v1/verify for a list of 10,000 addresses takes over half an hour at 300 requests per minute. One bulk job takes one request and runs at up to 100,000 emails per hour. If you poll job progress instead of using a webhook, poll every 5 seconds or slower.
Next steps#
Frequently asked questions
Do all my API keys share one limit?
Yes. Personal keys and OAuth connections to your personal account share your account's limit. Organization keys share one separate limit for the whole organization.
Does a bulk job count as one request?
Yes. POST /v1/verify/bulk counts as one request for up to 100,000 addresses, and a file upload counts as one request for up to 500,000. Use them instead of looping over POST /v1/verify.
How do I get a higher limit?
Buying credits once moves an account from 30 to 300 requests per minute, and a monthly or yearly subscription raises it to 600. For more, email support@rocketverifier.com with your expected volume and we set a limit on your key or organization.
Do sandbox requests count?
Yes. Requests with an rv_test_ key count against your account's limit, and sandbox requests without a key count against the anonymous limit of 5 per minute per IP.
Updated 11 November 2026Suggest an edit