Get started

# Errors

POST errors use the Connect JSON format. Check the HTTP status before reading a successful response.

Example error 

```
{
  "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](https://opengeocoding.com/docs/protocols).

Canonical page: https://opengeocoding.com/docs/errors