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.

View as Markdown

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_exceeded until 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/usage returns 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.