Rate limits and quotas

Two limits apply to every caller: a daily quota, which decides when billing starts, and a burst limit in requests per second, which protects the service from loops and stampedes. Both are reported in response headers on every request.

The daily quota

The day is the UTC calendar day. There is no rolling window: at 00:00 UTC every counter is zero again. X-Quota-Reset carries the exact Unix time.

Why IPv6 is counted per /40

An IPv4 address is a reasonable stand-in for one machine or one household. An IPv6 address is not: ISPs hand each customer a /64 (18 quintillion addresses) or a /56, and hosting providers hand out /48s. Counting per address would let a single script rotate through fresh addresses forever. Counting per /40 puts a limit on one customer pool or one hosting region, which is close to what one IPv4 address represents.

The trade-off is that on some networks you share a /40 with other users, and their traffic can use up "your" free requests. If that happens, attach a key or whitelist your addresses; account usage is never counted per block.

Burst limits

The limit is measured over a sliding one-second window per IP address or account. Concurrent connections are not limited separately. If you need more than 50 a second for a batch job, write to us; raising it is routine. Or spread the job: 50 a second is 180,000 an hour.

What counts as a request

• Every successful call (200) to any endpoint counts as one, whether or not it found anything.
• Elevation calls count one per point. IP batch calls count one per address. MapQuest and Geocodio batch endpoints on the drop-in hosts count one per location.
• Calls refused with 400, 401, 403, 404 or 429 do not count.
• Calls that fail with 500 or 503 do not count.
• Map tiles, style JSON and library loads from the JavaScript drop-ins do not count.

Reading the headers

x-quota-limit: 2500        # free per day; -1 on Unlimited
x-quota-used: 2431         # counted today, including this request
x-quota-billable: 0        # accounts: requests above the free allowance today
x-credits-remaining: 148200 # accounts with credits: balance after this request
x-quota-reset: 1756339200  # Unix time of the next 00:00 UTC
x-ratelimit-limit: 50      # burst limit per second
x-ratelimit-remaining: 47  # left in this second
x-request-id: 01J6F3ZK9W2R8Q5V7N4M1B0CXE

Handling 429

There are two different 429 responses and they deserve different handling:

{ "status": "error", "error": { "code": "rate_limited", "message": "Burst limit of 50 requests per second exceeded. Retry after 1 second." } }

Wait a second and retry. A short exponential backoff starting at 200 ms works well. The Retry-After header is set to 1.

{ "status": "error", "error": { "code": "quota_exceeded", "message": "Daily allowance of 2,500 requests used. Resets at 2026-08-28T00:00:00Z. Attach an API key or whitelist this IP to continue." } }

Do not retry in a loop; the answer will be the same until midnight UTC. Read X-Quota-Reset and either wait, or fail the operation and tell the user, or attach an account. Retry-After is set to the number of seconds until the reset.

Accounts whose credit balance has run out get 402 no_credits for requests above the free allowance. It behaves like quota_exceeded: top up, or wait for the reset. The dashboard emails you when the balance drops below 20% and again at zero.

Reducing requests

You may cache results indefinitely, so do. Addresses do not move; the same forward geocode tomorrow is the same answer. IP blocks change slowly; a day is a safe cache time. Timezone rules for a point change rarely and the IANA name essentially never. For autocomplete, debounce input to about 150 ms and stop sending once the user has picked a suggestion.