Error handling
Handle provider failures, caller deadlines, and empty results.
A valid geocode, search, or reverse-geocode request with no matches is a success with an empty result list. Test for emptiness before accessing candidates. Do not use exceptions to detect no-match results for those methods.
Autocomplete similarly returns an empty suggestions list after eligible fallback processing. Selection resolution is different: it promises one address, so an empty primary lookup raises GeocodingError with code provider_error. Lookup failures call no alternative provider and have no provider-chain attempt history. See resolution behavior.
SDK errors
GeocodingError includes the provider, a string code, optional HTTP status, and ordered attempt history. TypeScript/Python expose code; PHP exposes errorCode and serializes it as code. C# exposes Provider, Code, Status and Attempts. PHP's inherited getCode() is numeric and is not the SDK error code.
| Code | Meaning | Primary can trigger fallback? |
|---|---|---|
http | Non-success HTTP status | Only status 500–599, when server_error is enabled |
network | Connection failure or successful-body read failure | Yes, when enabled |
timeout | Per-provider request timeout | Yes, when enabled |
invalid_response | Invalid JSON or malformed response shape | No |
provider_error | Backup application-level failure, including Google errors with HTTP 200 | A failed backup advances to the next configured provider |
unsupported_country | Country routing skipped primary and no backup returned results | Terminal country-routing error |
Empty or failed backup responses advance to the next provider. If all backups are exhausted and primary succeeded, the SDK returns primary results; if primary failed, the original primary error is raised with all attempts attached.
Caller control errors
Cancellation and total deadline expiration stop the chain and are separate from eligible provider outages. TypeScript propagates the signal's reason; Python uses TimeoutError / asyncio.CancelledError; PHP uses RequestTimeoutException / RequestCancelledException; C# uses OperationCanceledException.
Invalid client settings fail before a network call: typically TypeError in TypeScript, ValueError in Python, InvalidArgumentException in PHP, and ArgumentException in C#. Invalid primary request fields are validated by the API and surfaced as HTTP errors.
Error text and logging
Primary HTTP error messages include the status and any error, message, or nested error.message text from the response body. The SDK redacts configured API keys and HTTP URLs, removes control characters, and limits that text to 512 characters. It omits full error bodies. An unreadable HTTP error body preserves the status and fallback policy.
Record provider, code, status, fallback reason, and attempt outcomes to distinguish a recovered primary outage from complete exhaustion. Avoid logging raw provider response bodies if your application should not retain customer address data. For TypeScript, explicitly select error properties for JSON logging; Python error.to_dict() and PHP json_encode($error) serialize nested attempts. C# serializes GeocodingError and its attempts with JsonSerializer.Serialize(error, GeocodingClient.JsonOptions).
See HTTP errors for status details and the language-specific usage guides for exception handling examples.