Skip to main content
Every error is one RFC 9457 body with a code you can switch on. This page shows the five codes a new key meets first. Each step says when the code occurs, shows the body, quotes the recovery sentence of the Errors page and names the one thing to check.
1

401 unauthorized: no key, or a wrong key

The request carries no Authorization header, or you mistyped the key, or the console revoked or deleted it. The gateway answers before the request reaches the API, so the response carries the id as zp-rid.
The Errors page says: “Send Authorization: Bearer with a current key. A revoked or mistyped key gets the same answer.”Check one thing: the header reads Authorization: Bearer zpka_... with the whole key. Your keys says how to copy it again and how to roll it.
2

403 quota_exceeded: you spent the period's credits

Your requests spent the plan’s credits for the billing period. On Growth and Scale the answer comes at the overage ceiling instead. Every route that charges credits answers it until the period resets or the plan changes.
The Errors page says: “Upgrade the plan in the developer console, or wait for the billing period to reset.”Check one thing: X-Credits-Remaining on your last charged response. It counts down to 0, or to the ceiling on Growth and Scale. Plans and limits says what a credit is and when the period resets.
3

429 rate_limited: too many requests this minute or today

You spent a request budget. The gateway checks the plan’s requests a minute and a day first. The API keeps budgets of its own, and the body’s bucket names the budget that refused. The Retry-After header carries the seconds to wait.
The Errors page says: “Retry after retry_after seconds.”Check one thing: wait Retry-After seconds, then send the same request again. Do not retry at once. Rate limits has the retry rule.
4

422 outside_coverage: no data at this location

The point, viewport, ZIP or city lies outside every loaded market. The API refuses, and does not serve an empty page: an empty page means zero measured. For a ZIP or a city the API cannot place, the body also carries markets[]. The field lists the codes of the loaded markets.
The Errors page says: “No data at this location. Read the loaded markets and their areas from markets[] when present, and from meta.coverage[] on any list response.”Check one thing: Which data is available where lists every loaded market with its counties and ZIP codes. GET /v1/coverage answers the same question for one point, ZIP or county at 0 credits.
5

400 invalid_cursor: the page cursor is stale

The cursor came from another query, another sort or an earlier data version. The API cannot read it, so it refuses the page and does not serve the wrong rows.
The Errors page says: “Restart from page 1 without cursor. The data refreshed or the query changed.”Check one thing: meta.coverage[].dataset_version on your first page. If it moved, the data refreshed and every cursor of the old version is stale. Pagination has the cursor rule.

​
What to send to support

Use the support channel your plan names on Plans and limits. That table also gives the first-response target of each plan. The Free plan has no support channel yet. On a Free key, read the Errors page and keep the request id. Send four things:
  • The request_id from the body, or the X-Request-Id header. A refusal the gateway answers itself carries the id as zp-rid.
  • The UTC time of the request.
  • The code.
  • The request as you sent it, without the key.
Request ids says why the id matters on a 200 too.

​
Where to go next

Errors

Every code the API can return, with its body and what to do.

Rate limits

The per-minute and per-day limits, the 429 body and the one retry rule.

Plans and limits

What a credit is, the plans, the refusals at a limit and support.