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. You can find the quotas included in each plan on the pricing page.
Not every request counts
Only successful calls count against your quota. Any error on our side or validation errors (e.g., wrong parameter) will NOT count against your quota or rate limit.
Request costs
A call does not always count as one request. Successful responses from the data endpoints include an X-Cost header telling you how many requests that call counted against your quota (0 for sandbox keys and free endpoints). /v1/status responses and error responses do not carry an X-Cost header.
- Name
/v1/search- Type
- Description
1 request per postal code found.
- Name
/v1/validate- Type
- Description
1 request per call.
- Name
/v1/autocomplete- Type
- Description
1 request per call.
- Name
/v1/reverse- Type
- Description
1 request per call.
- Name
/v1/distance- Type
- Description
1 request per successful distance calculation (compared codes that are not found are free).
- Name
/v1/radius- Type
- Description
10 requests per call.
- Name
/v1/polygon- Type
- Description
10 requests per call.
- Name
/v1/match- Type
- Description
1 request per call.
- Name
/v1/code/city- Type
- Description
1 request per 10 postal codes returned (at least 1).
- Name
/v1/code/state- Type
- Description
1 request per 10 postal codes returned (at least 1).
- Name
/v1/country/province- Type
- Description
Free.
- Name
/v1/coverage- Type
- Description
Free.
- Name
/v1/status- Type
- Description
Free — does not count against your quota or rate limit.
Response Headers
We attach specific headers to tell you your current monthly/minute quota, how much you have remaining in the period, and how many requests the call counted.
X-Cost: 1
X-RateLimit-Limit-Quota-Minute: 5
X-RateLimit-Limit-Quota-Month: 300
X-RateLimit-Remaining-Quota-Minute: 3
X-RateLimit-Remaining-Quota-Month: 199
The -Quota-Minute headers are only sent on the free plan; paid plans do not receive them. The minute headers count on the gateway node that answered the request: X-RateLimit-Limit-Quota-Minute shows that node's limit (5), and with our two gateway nodes that makes the 10 requests per minute of the free plan. X-RateLimit-Remaining-Quota-Minute is what is left on that node.
Grace and overage quotas
If a payment for your subscription is pending or has failed, we do not cut off API access immediately. Instead, your account temporarily runs on a grace quota. While a grace quota is active, requests count against it instead of your monthly quota, and the API reports it via these headers (as well as the grace bucket in the status endpoint response):
x-ratelimit-limit-grace-month: 300
x-ratelimit-remaining-grace-month: 120
Once the payment completes, your regular monthly quota applies again. If the grace quota runs out before that, the API returns a 429 status code asking you to complete your payment.
If your plan has overages enabled, requests beyond your exhausted monthly quota draw from your overage allowance instead of failing, reported via:
x-ratelimit-limit-overage-month: 100
x-ratelimit-remaining-overage-month: 40
When the overage allowance is exhausted as well, the API returns a 429 status code.