Errors
Failures are RFC 9457 problem details (application/problem+json). Branch on code, show detail, and quote request_id when you contact us.
{ "type": "https://geo-coder-service.vercel.app/docs/errors#quota_exceeded", "title": "quota_exceeded", "status": 402, "detail": "This month's units on the Free plan are used up. Upgrade at /pricing or wait for the 1st.", "code": "quota_exceeded", "request_id": "6c0b6c1e-…", "used": 1000, "limit": 1000}type links to this page at the code's anchor. MCP tools return the same code and detail as a tool error, and the CLI prints them to stderr with a non-zero exit code.
400
invalid_inputHTTP 400
The input failed validation: a missing field, a wrong type, a value out of range.
Fix: Read detail (and issues for each field) and fix the request. The op's reference page lists every field.
invalid_jsonHTTP 400
The body (or ?input=) is not valid JSON.
Fix: Send a JSON object with Content-Type: application/json, or URL-encode the JSON in ?input=.
invalid_idHTTP 400
The boundary id can't be read.
Fix: Use r<relation id> or w<way id>; R62422, relation/62422, an osm.org URL, wikidata:Q64 and iso:US-CA are accepted too.
no_childrenHTTP 400
Only administrative boundaries have subdivisions; this one is a postcode or another kind.
Fix: Call list_children on an administrative boundary, e.g. the city that contains the postcode.
too_many_boundariesHTTP 400
A union names more boundaries than one call allows.
Fix: Split the union into several calls, or union the parents instead of every child.
access_deniedHTTP 400
CLI sign-in: the person declined the device code.
Fix: Start geocode login again.
expired_tokenHTTP 400
CLI sign-in: the device code expired before it was approved.
Fix: Start geocode login again.
invalid_grantHTTP 400
CLI sign-in: the device code is unknown or was already used.
Fix: Start geocode login again.
401
invalid_keyHTTP 401
The API key doesn't exist or was revoked.
Fix: Create a new key in the dashboard and replace the old one.
invalid_tokenHTTP 401
The OAuth access token (MCP connectors, dashboard) is invalid or expired.
Fix: Sign in again; MCP clients refresh tokens on their own.
402
quota_exceededHTTP 402
This month's units on your plan are used up. used and limit say by how much.
Fix: Upgrade at /pricing, or wait for the 1st. Free calls (search, children) keep working.
404
not_foundHTTP 404
No such boundary, key or resource.
Fix: Check the id. Search by name to find the right one.
no_geometryHTTP 404
The boundary exists but OpenStreetMap has no polygon for it.
Fix: Use its parent, or describe the area with create_area.
405
method_not_allowedHTTP 405
The op changes state, so it can't be called with GET.
Fix: Send it with POST.
409
too_many_keysHTTP 409
The account already has the maximum number of active keys.
Fix: Revoke a key you no longer use.
413
too_largeHTTP 413
The result is too big for one response, e.g. a union at high detail.
Fix: Ask for a lower detail, or export the boundaries one by one.
422
could_not_mapHTTP 422
Areas couldn't turn the description into a validated polygon. detail lists each place that was not found or was ambiguous.
Fix: Make the wording more specific (add the country, the kind of place), or split it into parts.
428
429
rate_limitedHTTP 429
Too many requests this minute. retry_after gives the seconds to wait.
Fix: Wait retry_after seconds, then retry; add a key (or upgrade) for a higher limit.
500
internal_errorHTTP 500
Something failed on our side.
Fix: Retry with backoff. If it persists, email us the request_id.
502
503
geometry_pendingHTTP 503
Another request is fetching this boundary's polygon from OpenStreetMap right now.
Fix: Retry after a few seconds; the polygon is then served from cache.
upstream_busyHTTP 503
OpenStreetMap's services are rate-limiting us, so a boundary not yet cached can't be fetched this second.
Fix: Retry after a few seconds. Cached boundaries are never affected.