api reference
Rate limits and quotas
How quotas work: the free tier counts checks per day, paid plans per month with no daily limit. Per-second and in-flight limits, how batch and deep checks count, rate-limit headers, and how to handle 429 responses.
Every account starts free on tier 0. Higher tiers are monthly plans you switch on yourself in Plans & billing. These are the defaults; we can change them, and we can raise them for you.
Free counts per day, paid plans per month
- Free (tier 0): 100 checks a day. The quota resets at 00:00 UTC. When it’s used up, the API answers
429 quota_exceededuntil the reset. - Paid plans (tiers 1 to 3): checks per month, no daily limit. The month is your billing month, from the date you subscribed to the same date the next month. Use the month however you like: all of it on one day is fine.
- Paid plans never stop at their included checks. Checks past them keep working and are billed at your plan’s rate per 1,000. You don’t wait for the end of the month to pay for them: each time they add up to €10, your card is charged for them, and anything below that goes on the next monthly invoice.
- Every tier has a per-second limit (and an in-flight limit), whatever its quota.
Tiers
| Tier | Plan | Quota | Per second | Batch requests per second | In flight |
|---|---|---|---|---|---|
| 0 | Free | 100 checks a day | 5 | 1 | 10 |
| 1 | Paid | 10,000 checks a month, then billed per 1,000 | 10 | 1 | 10 |
| 2 | Paid | 50,000 checks a month, then billed per 1,000 | 20 | 2 | 20 |
| 3 | Paid | 300,000 checks a month, then billed per 1,000 | 200 | 10 | 50 |
- Prices are shown in your dashboard under Plans & billing. Cancel any time; the tier stays until the end of the paid month.
- Need more than tier 3, or custom limits? Contact us with your use case and expected volume.
- Limits are per account, shared by all its keys. Publishable keys (the ones in web pages) also stop at 2,000 checks a day, so a copied browser key can’t use up your month.
- An account we moved to a paid tier by hand, without a subscription, counts per calendar month (UTC) and stops at the limit, since there is nothing to bill.
- These are the defaults. Your dashboard’s Settings page shows the limits that apply to your account right now, and
GET /v1/usagereturns them.
What counts
| Request | Counts as |
|---|---|
/v1/check |
1 |
/v1/check with deep=true |
5 (and at most 1,000 deep checks a day) |
/v1/check/batch |
1 per item (up to 100 items per request). Batch requests also have their own per-second limit, see the table above |
/v1/verify |
1, given back when the answer is unknown. Verifications also have their own daily cap, see Verify |
/v1/feedback |
0 checks; separate limit of 50 a day per key |
/v1/usage, /v1/health |
0 |
| Test addresses | 0, never counted |
The free tier’s quota resets at 00:00 UTC; a paid plan’s at the start of your next billing month.
Headers
Every counted response carries rate-limit headers in both the standardized and the legacy format:
| Header | Meaning |
|---|---|
RateLimit-Policy |
The limits that apply to you, in the format of the IETF HTTPAPI RateLimit header fields draft: a "day" or "month" quota, plus the burst limit |
RateLimit |
Current remaining allowance and time to reset, same draft |
X-RateLimit-Limit |
Your quota: checks a day on the free tier, included checks a month on a paid plan |
X-RateLimit-Remaining |
Checks left in the current day or month. On a paid plan it stays at 0 once the included checks are used, while checks keep working (and are billed) |
X-RateLimit-Reset |
Seconds until the quota resets |
Retry-After |
On 429 (and 503): seconds to wait before retrying |
Parse whichever your HTTP client already understands.
Errors
| Code | Status | Meaning | What to do |
|---|---|---|---|
rate_limited |
429 | Too many requests per second, or too many in flight | Wait Retry-After seconds, retry with backoff and jitter |
quota_exceeded |
429 | Free tier: today’s 100 checks are used up. (Paid plans never get this for their monthly checks.) | Stop until 00:00 UTC, or switch on a paid plan. Signups should fail open. |
batch_too_large |
413 | More than 100 items | Split the batch |
payload_too_large |
413 | Body over 256 KB | Send smaller batches |
When you hit the free tier’s quota we send one email that day with your usage and a link to the paid plans.
Handling 429 well
async function checkWithRetry(body, attempts = 3) {
for (let i = 0; i < attempts; i++) {
const res = await fetch('https://api.isbusinessemail.com/v1/check', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.IBE_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(body),
signal: AbortSignal.timeout(2500),
});
if (res.status !== 429) return res;
const problem = await res.json();
if (problem.code === 'quota_exceeded') return res; // retrying won't help until the reset
const wait = Number(res.headers.get('Retry-After') ?? 1) * 1000;
await new Promise((r) => setTimeout(r, wait + Math.random() * 250));
}
throw new Error('rate limited');
}
For a live signup form, don’t retry at all: fail open and re-check in the background.
Staying well under your limits
- Cache on your side by domain. Verdicts for a domain rarely change within a day.
- Check once per signup, on submit, not on every keystroke. For inline hints, debounce and use a publishable key, which has its own limits.
- De-duplicate before batch jobs, and check domains instead of addresses when you only need the company.
Fair use
Limits exist to keep the service free. Creating multiple accounts to get around them, rotating IPs, or reselling access are against the Acceptable Use Policy and lead to suspension. If you need more, ask; we say yes to most reasonable requests.