Get started
Errors
POST errors use the Connect JSON format. Check the HTTP status before reading a successful response.
{
"code": "invalid_argument",
"message": "The query is empty."
}| HTTP | Code | Meaning |
|---|---|---|
| 400 | invalid_argument | Invalid JSON, unknown fields, unknown or repeated query parameters, unsupported Connect protocol version, oversized body, invalid query or unverifiable client address. |
| 401 | unauthenticated | The API key is missing, invalid, expired or revoked. |
| 403 | permission_denied | A browser key was used without an Origin header, from an origin not in its allowed list, or over gRPC. |
| 404 | not_found | The suggestion ID is unknown or belongs to an older index. Request autocomplete suggestions again. |
| 429 | resource_exhausted | The per-second limit was reached, a billable operation has no remaining credits, or the client IP is temporarily locked after failed API authentication. Autocomplete and regions remain available with zero credits. IP lockouts include Retry-After and also block valid keys from that IP until expiry. |
| 503 | unavailable | The API is starting or the geocoder is temporarily unavailable. |
Retry safely
Fix the request before retrying a 400. Replace or correct the key for a 401. For a 403, call
with a browser key from one of its allowed origins, or use a secret key from your server.
For a rate-limit 429, honor Retry-After; for exhausted credits, restore the
balance first. For a 503, retry with exponential backoff and jitter.
Lookups are read-only, but a response lost in transit may already have spent a credit. Retrying it can spend another. Failed responses do not spend credits.
JSON conventions
Use camelCase field names. Protobuf snake_case names are also accepted. Unknown fields are
rejected. Default scalar values and empty lists may be omitted from replies. The optional Connect-Protocol-Version header must be 1 if supplied.
Other transports
Native gRPC uses status codes in trailers, not HTTP status alone. See gRPC.