Skip to main content

:::note Generated reference Generated from honeyframeapi 0.1.8 — do not edit by hand. :::

honeyframeapi.exceptions

Exception hierarchy for the Honeyframe Python SDK.

A single base class (HoneyframeError) that callers can catch broadly, plus typed subclasses for the HTTP error classes the platform returns so scripts can react to specific failures (auth expiry, missing resources, validation).

class HoneyframeError​

Bases: Exception

Base class for every error raised by the SDK.

class HoneyframeConfigError​

Bases: HoneyframeError

Raised when the client is misconfigured (missing creds, bad URL).

class HoneyframeAPIError​

HoneyframeAPIError(status_code, detail, *, method=None, url=None, response=None)

Bases: HoneyframeError

Raised when the platform returns a non-2xx HTTP response.

Attributes

status_code: The HTTP status code. detail: The parsed detail field from the JSON body (FastAPI convention), or the raw response text when the body is not JSON. method, url: The request that failed, for debugging. response: A copy of the httpx.Response (when available) for advanced inspection: status, headers and body are kept, but its .request has no Authorization / Cookie / X-API-Key header and no body.

class HoneyframeAuthError​

Bases: HoneyframeAPIError

401/403 — token missing, expired, or insufficient permission.

class HoneyframeNotFoundError​

Bases: HoneyframeAPIError

404 — the requested resource does not exist or is out of scope.

class HoneyframeValidationError​

Bases: HoneyframeAPIError

400/409/422 — the request body or a uniqueness constraint was rejected.

class HoneyframeRateLimitError​

HoneyframeRateLimitError(status_code, detail, *, retry_after=None, **kwargs)

Bases: HoneyframeAPIError

429 — a rate/concurrency limit was hit. Retrying is correct.

Attributes

retry_after: Seconds to wait before retrying, from the Retry-After response header. None when the header is absent, negative, or in the HTTP-date form (which this SDK deliberately does not interpret — callers should fall back to their own backoff).

The SDK never auto-retries a 429: only the caller knows whether waiting retry_after seconds inside the current process is acceptable.

class HoneyframeBudgetExceededError​

Bases: HoneyframeAPIError

429 budget_exceeded — the org's metered budget is spent.

Never retryable. Unlike HoneyframeRateLimitError, this does not clear on a timer: the quota resets with the billing month. Retrying burns attempts and cannot succeed — surface it to a human (raise the budget, or wait for the reset) instead of backing off.

Distinguishing the two is the whole point of the 429 branch: the upstream gateway returns both as 429, and collapsing them would turn a month-long block into a retry loop.

Functions​

error_code_from_body()​

error_code_from_body(detail: Any, response: Any = None) -> Optional[str]

Best-effort error code for an error response.

Two body shapes are live and neither is negotiable from this side: FastAPI's {"detail": <str|dict>} and the gateway's {"error": {"code": ...}}. detail alone is not enough — _safe_detail falls back to the raw text when there is no detail key, so the gateway shape only survives on the response object.

error_for_status()​

error_for_status(status_code: int, detail: Any, *, method: Optional[str] = None, url: Optional[str] = None, response: Any = None) -> HoneyframeAPIError

Map an HTTP status code to the most specific SDK exception class.

Constants​

NameValue
MAX_DETAIL_CHARS4096

Verified against honeyframeapi 0.1.8.