Quotas and rate limits

Two independent limits: how many requests you get per month, and how fast you may send them.

Monthly quota

Each plan includes a fixed number of billable requests per billing period. When it runs out, further requests are refused with quota_exceeded until the period resets. There is no overage billing. You can never receive a surprise invoice, because the only way to spend more is to choose a bigger plan.

What counts

On a paid plan one rule covers every case: a request is billable if and only if you received a check result. The free plan is stricter, and the two lines below say where.

• A 200 with a score counts.
• A cached answer counts. You got a result, and free cache hits would let anyone poll one address forever at no cost.
• Refusals are always free: bad keys, rate limits, an exhausted quota. A failed lookup, whether a timeout or our own failure, is free on a paid plan and counts on the free one.
• Unknown addresses are free on a paid plan, up to a quarter of your plan; past that they start counting. They are free to you but cost us a scan, and an unlimited allowance would be an obvious way to abuse it. On the free plan they count from the first one.

Reading your quota from headers

Every response to an authenticated request carries your current position, already including the request you just made.

X-RateLimit-Limit: 500000
X-RateLimit-Remaining: 371557
X-RateLimit-Reset: 1788220800

X-RateLimit-Reset is a Unix timestamp for the end of the current period. These headers describe the monthly quota only. The per-minute limit signals itself with a Retry-After header and the rate_limited code instead.

Requests per minute

Separately from the monthly quota, each plan has a rate ceiling measured over a sliding minute. Exceeding it returns rate_limited with a Retry-After header, and costs nothing. This limit applies to every request, including the free ones. A refused request still takes work to refuse.

Changing plan mid-period

A plan change moves the limit, not the counter. Upgrading gives you the extra headroom immediately. Downgrading below what you have already used blocks further requests until the period ends. This is deliberate: a reset on every change would make the quota meaningless.

Retrying

Respect Retry-After. On a rate limit it is a few seconds; on an exhausted quota it points at the end of your billing period, so retrying before then will not help. Do not retry a 4xx other than 429. The answer will be the same.