honua-sdk › Errors

The SDK raises a focused hierarchy rooted at HonuaError. HTTP-shaped failures derive from HonuaHttpError, with HonuaAuthError (401/403) and HonuaRateLimitError (429) as the two specialized HTTP subclasses worth catching individually. Transport-level failures derive from HonuaTransportError, with HonuaTimeoutError for explicit deadline misses.

Catch HonuaError to handle any SDK failure; catch the narrower subclasses when you want retry or surfacing logic tuned to a specific failure mode. See Quickstart › Common errors for worked examples.

from honua_sdk import HonuaRateLimitError, HonuaTimeoutError

try:
    result = client.query_features("svc", 0)
except HonuaRateLimitError as exc:
    retry_after = exc.retry_after

See also: Quickstart › Common errors for retry recipes, and Clients for how timeout= and with_options(timeout=...) interact with HonuaTimeoutError.

honua_sdk.errors.HonuaError

Bases: Exception

Base exception for SDK failures.

Root of the SDK error hierarchy. Catch this (rather than the builtin :class:Exception) to scope try/except blocks to failures originating in honua-sdk transport, protocol, or capability resolution. Subclasses surface protocol-specific diagnostics (status code, request id, retry-after, gRPC status, etc.).

honua_sdk.errors.HonuaHttpError

Bases: HonuaError

Raised when an API request returns a non-success response.

Holds the HTTP status_code, a server-supplied message, and the raw response body (parsed JSON when available, raw text otherwise). The request_id attribute carries the server's correlation identifier (extracted from x-request-id, Honua-Request-Id, or X-Correlation-ID response headers, case-insensitive) when available, and headers exposes the full response headers as a plain dict for debugging.

Status-specific subclasses (:class:HonuaAuthError, :class:HonuaRateLimitError) are raised for well-known codes so callers can except them individually while still catching :class:HonuaHttpError for the general case.

Attributes:

Name	Type	Description
status_code		HTTP response status code.
message		Server-supplied error message (defaults to the response reason phrase when none was provided in the body).
body		Parsed JSON body when available, otherwise the raw response text or None.
request_id		Server correlation id parsed from the response headers (x-request-id / Honua-Request-Id / X-Correlation-ID), or None when not present.
headers	Mapping[str, str]	Full response headers as a plain dict[str, str].
error_code		The application-level error code reported by an Esri GeoServices error envelope (e.g. 498/499 token errors), when the failure originated from such an envelope. None for ordinary transport-level HTTP failures. Distinct from status_code because GeoServices codes are an application code space, not HTTP statuses.

honua_sdk.errors.HonuaAuthError

Bases: HonuaHttpError

HTTP 401/403 — authentication or authorization failure.

Subclass of :class:HonuaHttpError; existing except HonuaHttpError handlers catch these unchanged.

Attributes:

Name	Type	Description
status_code		401 (auth failure) or 403 (authorization failure).
message		Server-supplied error message.
body		Parsed JSON body when available, otherwise the raw text.
request_id		Server correlation id, when present in the response headers.
headers	Mapping[str, str]	Full response headers as a plain dict[str, str].

honua_sdk.errors.HonuaRateLimitError

Bases: HonuaHttpError

HTTP 429 — the server rejected the request as rate-limited.

Subclass of :class:HonuaHttpError. The optional retry_after attribute carries the parsed Retry-After response header (seconds) when present and well-formed, otherwise None.

Attributes:

Name	Type	Description
status_code		HTTP 429.
message		Server-supplied error message.
body		Parsed JSON body when available, otherwise the raw text.
retry_after		Parsed Retry-After value in seconds (float), or None when the header was absent / unparseable.
request_id		Server correlation id, when present in the response headers.
headers	Mapping[str, str]	Full response headers as a plain dict[str, str].

honua_sdk.errors.HonuaTransportError

Bases: HonuaError

Network-level failure with no HTTP response.

Covers DNS errors, connection refusals, TLS handshake failures, and other transport-level conditions where no HTTP status was received. Catch this (or its parent :class:HonuaError) for retry-style logic that does not depend on a response body. Wraps the underlying :class:httpx.HTTPError via the standard __cause__ chain when raised by the SDK transport layer.

honua_sdk.errors.HonuaTimeoutError

Bases: HonuaTransportError

Request exceeded the configured timeout.

Subclass of :class:HonuaTransportError; catch the parent class to treat timeouts and other transport failures uniformly. Raised when the underlying :class:httpx.Timeout (connect / read / write / pool) fires before the server returns a response.