Rate Limit & Quotas
You can use a certain number of API credits 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 enforce a minute rate limit for specific plans. 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
Endpoints consume a different number of credits per request. Successful responses from the data endpoints include an X-Cost header telling you how many credits that request 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 credit per postal code found.
- Name
/v1/distance- Type
- Description
1 credit per successful distance calculation (compared codes that are not found are free).
- Name
/v1/radius- Type
- Description
10 credits per request.
- Name
/v1/polygon- Type
- Description
10 credits per request.
- Name
/v1/match- Type
- Description
1 credit per request.
- Name
/v1/code/city- Type
- Description
1 credit per 10 postal codes returned (minimum 1).
- Name
/v1/code/state- Type
- Description
1 credit per 10 postal codes returned (minimum 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 credits the request consumed.
X-Cost: 1
X-RateLimit-Limit-Quota-Minute: 10
X-RateLimit-Limit-Quota-Month: 300
X-RateLimit-Remaining-Quota-Minute: 5
X-RateLimit-Remaining-Quota-Month: 199
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.