My Geocode

Guides

Handle a 429 response without losing the request

· 3 min read · My Geocode · #errors#rate-limits#429#retries

A 429 status code is not the same kind of failure as a 400 or a 404. It means the request was well formed and would have worked, but your allowance for the current period is used up.

What the response looks like

HTTP/1.1 429 Too Many Requests
X-Quota-Limit: 2500
X-Quota-Used: 2500
X-Quota-Free-Remaining: 0
X-Credits-Remaining: 0.00
X-Quota-Reset: 2026-09-22T00:00:00Z

{
  "status": "error",
  "error": {"code": "quota_exceeded", "message": "Daily quota exceeded"}
}

Do not discard the request

The most common mistake is treating a 429 the same way as a 400, logging it as a failure and moving on. The underlying lookup the user or your script wanted is still perfectly valid, it just needs to run later or under different credentials. Put the original request payload onto a retry queue instead of discarding it.

Reading the reset time

The X-Quota-Reset header on the 429 response tells you exactly when the daily allowance resets. A background job can sleep until that time and then resume the queue, rather than polling repeatedly or guessing at a fixed retry interval.

A second scenario worth planning for

A 429 does not always mean the whole day's allowance is gone. If X-Key-IPs-Used has reached X-Key-IPs-Limit, a key can be temporarily refused from a new source address even while requests from its usual addresses would still succeed. Checking which header actually explains the 429, quota exhaustion or an IP slot limit, changes what fixes it: waiting for a reset in one case, and reducing the number of distinct machines using the same key in the other.

Two ways past the limit right now

If waiting is not acceptable, there are two immediate options: top up prepaid credit at €0.0001 a request, or move to an Unlimited key at €50 a month if this is a recurring pattern rather than a one-off spike. Both remove the daily ceiling that triggered the 429 in the first place.

Separating key limits from network limits

Since the free allowance is shared across an entire /24 for IPv4 or /48 for IPv6, a 429 can happen because of traffic from other addresses on the same network, not just your own key's usage. Check X-Quota-Network-Used alongside X-Quota-Used to tell the two situations apart before deciding whether a key upgrade will actually fix anything.

A mistake worth avoiding

Retrying a failed request immediately, in a tight loop, the moment a 429 comes back only adds more failed calls on top of an allowance that is already exhausted, without moving you any closer to a working request. Back off to the reset time from the header, or to a sensible fixed delay if the code path does not read headers, rather than hammering the endpoint again right away.

Treating a 429 as "try again shortly" rather than "this failed" keeps a queue moving smoothly through a quota reset instead of losing work. Details on error shapes across the API are on the errors page, and current allowance options are on the pricing page.

More in Guides