Rate Limit & Quotas

You can use a certain number of requests per month, defined by your plan.

Once you go over this quota, the API returns a 429 HTTP status code, and you either need to upgrade your plan or wait until the end of the month. We also enforce a minute rate limit on the free plan: up to 10 requests per minute. If you exceed this, the API returns a 429 HTTP status code. You then have to wait until the end of the minute to make more requests. Not every request counts towards your monthly request volume.

Response Headers

We attach specific headers to tell you your current monthly/minute quota and how much you have remaining in the period.

X-RateLimit-Limit-Quota-Minute: 10
X-RateLimit-Limit-Quota-Month: 300

X-RateLimit-Remaining-Quota-Minute: 5
X-RateLimit-Remaining-Quota-Month: 199

X-Cost: 1

• X-RateLimit-Limit-Quota-Month / X-RateLimit-Remaining-Quota-Month report your monthly quota and how much of it is left.
• X-RateLimit-Limit-Quota-Minute / X-RateLimit-Remaining-Quota-Minute are only present on plans that have a minute rate limit (e.g. the free plan); on plans without one, these headers are not sent.
• X-Cost tells you how many requests the call counted against your quota (0 for sandbox requests). For a bulk job it is the number of unique, valid addresses in the list, charged when you submit it.

Grace & overage headers

In two situations your requests draw from a different quota bucket, reported by its own pair of headers:

• While a billing issue (e.g. a failed payment) is being resolved, your account runs on a temporary grace quota and responses carry X-RateLimit-Limit-Grace-Month / X-RateLimit-Remaining-Grace-Month instead of the monthly headers.
• If overage is enabled for your account and your monthly quota is used up, additional requests draw from your overage allowance and responses carry X-RateLimit-Limit-Overage-Month / X-RateLimit-Remaining-Overage-Month in addition to the (exhausted) monthly headers.

Bulk jobs

A bulk job costs one request per unique, syntactically valid address in the list, charged when you submit it. Duplicates and rows without a valid address are free, addresses we could not verify because of a failure on our side are refunded when the job completes, and deleting a job refunds the addresses not verified yet. Refunds go back to your current quota and cannot raise it above its size, so a refund after your monthly quota reset gives back at most the requests you have used since the reset. Checking a job, listing jobs, downloading results and deleting jobs are free.

• A list is only accepted if your monthly (or grace) quota has more requests left than the job costs. Otherwise the request is answered with 429 (quota_exceeded, or grace_quota_exceeded on a grace quota), and quota.required in the body says how many requests the job needs; nothing is stored or billed. Bulk jobs do not use the overage allowance.
• The minute rate limit counts requests, not calls: on the free plan, a job of 50 addresses uses up the minute's 10 requests, so further requests in that minute, including status checks, are answered with 429 until the minute is over.
• When your quota is used up, requests with your key are answered with 429, and that includes status checks and result downloads of bulk jobs. Download the results you need before your quota runs out.