Guides

Timeouts and cancellation

Bound provider requests and stop the complete chain.

Each SDK defaults to a ten-second timeout per provider HTTP request, including body reading. A provider timeout may trigger fallback. Without a caller deadline, a chain with multiple providers can take longer than ten seconds.

SDK	Per-provider constructor setting	Total deadline for one call
TypeScript	timeoutMs: 10000	{ signal: AbortSignal.timeout(15000) }
Python	timeout_ms=10000	timeout=15 (seconds)
PHP	'timeoutMs' => 10000	['timeoutMs' => 15000]

Total deadline expiration stops the chain. It does not advance to another provider.

The same per-provider and caller controls apply to autocomplete and selection resolution. Resolution makes one provider request and does not run fallback selection or use fallback budgets/circuit breakers. The browser client supports timeoutMs and RequestOptions.signal with the TypeScript units shown above.

Cancellation

• TypeScript: pass an AbortController's signal as the second method argument and call abort(). The caller's abort reason is propagated; it is not necessarily a GeocodingError.
• Python: cancel an async task or use an enclosing asyncio.timeout(...). asyncio.CancelledError stops the chain. Per-call deadline expiration raises TimeoutError.
• PHP: pass a CancellationToken in signal. Cancellation raises RequestCancelledException; caller deadline expiration raises RequestTimeoutException. The default cURL transport checks cancellation cooperatively.

Caller cancellation does not count as a provider circuit failure. A request reserved against the backup budget before cancellation still consumes that reservation.

Client lifetime

Reuse a client to share fallback budgets and circuit state. TypeScript and C# clients support concurrent requests. Python's blocking client supports concurrent threads; its async client must be used on one event loop and closed with aclose(). PHP's default cURL transport blocks its current execution thread; a custom yielding transport can support interleaved Fibers, but the SDK supplies no async scheduler.

Close Python clients or use their context managers. TypeScript/PHP clients do not expose a close method. See the language usage guides for examples.

Retries and overload

The SDKs do not retry automatically. When the primary service is temporarily unavailable it returns HTTP 503, which is eligible for default outage fallback during provider selection. Resolution does not switch providers on outages.

If your application retries, use bounded attempts with backoff and honor your account rate limits and Retry-After. Each repeated request can generate additional primary and backup calls. HTTP 429 does not trigger SDK fallback.

Custom transports

TypeScript accepts a standard fetch function; Python accepts an HTTPX async transport; PHP accepts TransportInterface; C# accepts HttpMessageHandler. Custom implementations must honor cancellation and deadlines. Redirects are not followed by the default SDK transports. See the individual client references for transport contracts.

For .NET, use the C# client. Its async methods accept CancellationToken; reuse a client to share backup budgets and circuit state.