Errors and limits
HTTP status codes, validation messages, and retry behavior.
Errors use a JSON object with a string error:
{"error":"'street' and at least one of 'city', 'state' or 'zip' are required."}
Some errors, such as authentication and rate-limit failures, use a message field instead. Inspect the HTTP status before parsing errors.
Status reference
| Status | Source / meaning | Action |
|---|---|---|
400 | Missing, unknown, repeated, or invalid query parameters | Correct the request; the message names the problem |
401 | Authentication failure | Check your apikey header and active key |
403 | Browser token used outside its origin or operation scope; or the organization lacks an active subscription or trial | Check the token and account billing status |
404 | Unsupported path or method | Use a documented GET endpoint |
429 | Account rate limit | Respect your deployment's limit and applicable response headers |
500 | Unexpected geocoder error | Handle as a service failure |
502 | The geocoding service returned an invalid response | Handle as a service failure |
503 | Geocoding, billing authorization, or a billing transition is temporarily unavailable | Retry with backoff |
Other HTTP statuses are possible. The SDK handles any primary HTTP 4xx as terminal and permits fallback for primary 500–599 when server_error is enabled.
Validation messages
| Example message | Cause |
|---|---|
Unknown parameter 'text'; use 'q'. | A parameter from an older API version; the message names the replacement |
Unknown parameter 'radus'. Allowed: lat, lon, radius, types, exclude_sources, limit. | Misspelled or unsupported parameter |
Parameter 'q' was given more than once. | Repeated parameter |
'q' must be at most 256 bytes. | Value too long after trimming |
'q' is required, e.g. q=1600 Pennsylvania Ave, Washington DC. | Missing search text |
'street' and at least one of 'city', 'state' or 'zip' are required. | Incomplete geocode request |
'lat' and 'lon' are required, e.g. lat=34.0522&lon=-118.2437. | Missing reverse coordinates |
'lat/lon' is out of range: latitude must be in [-90, 90] and longitude in [-180, 180]. | Invalid coordinates |
'near' must be 'lat,lon', e.g. near=34.05,-118.24. | Malformed near |
'bbox' must be 'minLon,minLat,maxLon,maxLat' with min <= max. | Malformed bbox |
'limit' must be a whole number from 1 to 40. | Invalid limit |
'min_confidence' must be a number from 0 to 1. | Invalid geocode min_confidence |
'radius' must be in meters, from 1 to 100000. | Invalid reverse radius |
Unknown type 'planet'. Allowed: address, venue, street, zip, ... | Invalid types value |
'country' must be a 2- or 3-letter country code, e.g. US. | Invalid country |
'exclude_sources' must be up to 32 comma-separated source names, ... | Invalid source exclusions |
'id' accepts at most 20 ids. | Too many place ids |
These are examples, not an exhaustive message list. Use statuses for application logic rather than exact string matching.
Retry behavior
Neither the API nor the SDKs retry failed requests automatically. SDKs can use configured backups on eligible outages. A caller retry can produce another metered primary request and additional paid provider calls.
If implementing retries, bound the attempt count, use backoff, and honor relevant Retry-After values. SDK backups do not run on 429 or other 4xx. Invalid requests and failures are not billed.