`yggdrasil.exceptions`¶

exceptions ¶

Library-wide exception types — the single canonical surface.

Every exception yggdrasil raises on its own derives from :class:YGGException so callers can write::

try:
    do_yggdrasil_things()
except YGGException:
    ...

and catch every error this library deliberately raises in one branch. Specialised types live in peer modules and are re-exported here so from yggdrasil.exceptions import <Anything> always works:

:mod:yggdrasil.exceptions.cast → :class:CastError
:mod:yggdrasil.exceptions.http → :class:HTTPError and the full HTTP status / connection / pool / location hierarchy.

When you need a new exception type, add it here (or in a peer file under :mod:yggdrasil.exceptions) — don't define ad-hoc local exception classes in feature modules. See AGENTS.md → "Centralise exceptions in :mod:yggdrasil.exceptions" for the rule and the worked example.

APIError ¶

APIError(detail: str = '', *, status_code: int | None = None)

Bases: YGGException

Base for every API-handler exception. Carries HTTP semantics.

BadRequestError ¶

BadRequestError(detail: str = '', *, status_code: int | None = None)

Bases: APIError

400 Bad Request.

APIConflictError ¶

APIConflictError(detail: str = '', *, status_code: int | None = None)

Bases: APIError

409 Conflict.

APIForbiddenError ¶

APIForbiddenError(detail: str = '', *, status_code: int | None = None)

Bases: APIError

403 Forbidden.

MethodNotAllowedError ¶

MethodNotAllowedError(detail: str = '', *, status_code: int | None = None)

Bases: APIError

405 Method Not Allowed.

APINotFoundError ¶

APINotFoundError(detail: str = '', *, status_code: int | None = None)

Bases: APIError

404 Not Found.

APITimeoutError ¶

APITimeoutError(detail: str = '', *, status_code: int | None = None)

Bases: APIError

408 Request Timeout.

TooManyRequestsError ¶

TooManyRequestsError(detail: str = '', *, status_code: int | None = None)

Bases: APIError

429 Too Many Requests.

APIUnauthorizedError ¶

APIUnauthorizedError(detail: str = '', *, status_code: int | None = None)

Bases: APIError

401 Unauthorized.

UnprocessableError ¶

UnprocessableError(detail: str = '', *, status_code: int | None = None)

Bases: APIError

422 Unprocessable Entity.

YGGException ¶

Bases: Exception

Root of every exception the yggdrasil library raises on its own.

CastError ¶

CastError(
    reason: str,
    *,
    source: "Field | None" = None,
    target: "Field | None" = None,
    original: BaseException | None = None
)

Bases: YGGException, ArrowInvalid

Raised when casting a value / array / table to a target field fails.

Carries the source and target :class:Field so the message can name which column was being cast — without these, debugging a multi-column write meant guessing which child raised. Subclassing :class:pyarrow.ArrowInvalid keeps every existing except pa.ArrowInvalid handler in the wider codebase catching these unchanged; subclassing :class:YGGException lets a generic except YGGException catch every error this library raises.

Message shape (single line so logs stay readable):

::

cast payload: string -> payload: list<struct<a:int64, b:string>> failed:
Invalid JSON at row 0: ... Value: 'pypsa'.

original preserves the underlying exception for raise ... from chains and for callers that want the raw pyarrow / json failure object.

LokiError ¶

Bases: YGGException

Base for every error the Loki agent raises on its own.

TokenBudgetExceeded ¶

TokenBudgetExceeded(used: float, limit: float, message: str | None = None)

Bases: LokiError

Raised when USD spend would exceed the configured cost budget.

Carries the running :attr:used spend and the :attr:limit it crossed (both USD) so a caller (the interactive CLI) can show the gap and offer to raise the cap step by step.

AuthRequiredError ¶

AuthRequiredError(message: str, *, request: 'PreparedRequest')

Bases: RequestError

Raised when an operation needs an :class:Authorization handler but none is bound — either on the request or on the session.

Fired by :meth:Session.refresh_auth when force=True (the default) and the caller has not configured any auth source. The silent no-op branch is reserved for force=False, which is what :meth:Session.prepare_request_before_send uses on steady-state sends (a request to a public endpoint shouldn't fail just because the session doesn't have a token to refresh).

BadGatewayError ¶

BadGatewayError(message: str, *, response: 'Response')

Bases: ServerError

502 Bad Gateway.

urllib3_response `property` ¶

urllib3_response

Return the bound :class:~yggdrasil.http_.HTTPResponse.

After the pool / response merge, the high-level :class:HTTPResponse carries the full urllib3-shaped surface (.status / .headers / .read / .stream / .release_conn / .drain_conn / .data) directly, so the explicit shim is gone — the response IS the shim.

to_starlette ¶

to_starlette() -> 'StarletteResponse'

Convert to a starlette.responses.JSONResponse suitable for returning directly from a Starlette or FastAPI exception handler.

The JSON body follows the RFC 7807 Problem Details shape::

{
    "status":  404,
    "error":   "Not Found",
    "detail":  "<exception message>",
    "path":    "/v1/contents/42/data",
    "method":  "GET"
}

retry_after is appended (and the Retry-After header set) when the exception carries that attribute (429 / 503).

to_fastapi ¶

to_fastapi() -> 'FastAPIJSONResponse'

Convert to a fastapi.responses.JSONResponse.

FastAPI's JSONResponse is a subclass of Starlette's, but returning the FastAPI type keeps FastAPI's exception handler machinery (background tasks, middleware hooks, OpenAPI error modelling) working correctly.

Falls back to to_starlette() transparently when FastAPI is not installed.

BadRequest ¶

BadRequest(message: str, *, response: 'Response')

Bases: ClientError

400 Bad Request.

urllib3_response `property` ¶

urllib3_response

Return the bound :class:~yggdrasil.http_.HTTPResponse.

After the pool / response merge, the high-level :class:HTTPResponse carries the full urllib3-shaped surface (.status / .headers / .read / .stream / .release_conn / .drain_conn / .data) directly, so the explicit shim is gone — the response IS the shim.

to_starlette ¶

to_starlette() -> 'StarletteResponse'

Convert to a starlette.responses.JSONResponse suitable for returning directly from a Starlette or FastAPI exception handler.

The JSON body follows the RFC 7807 Problem Details shape::

{
    "status":  404,
    "error":   "Not Found",
    "detail":  "<exception message>",
    "path":    "/v1/contents/42/data",
    "method":  "GET"
}

retry_after is appended (and the Retry-After header set) when the exception carries that attribute (429 / 503).

to_fastapi ¶

to_fastapi() -> 'FastAPIJSONResponse'

Convert to a fastapi.responses.JSONResponse.

FastAPI's JSONResponse is a subclass of Starlette's, but returning the FastAPI type keeps FastAPI's exception handler machinery (background tasks, middleware hooks, OpenAPI error modelling) working correctly.

Falls back to to_starlette() transparently when FastAPI is not installed.

CacheError ¶

CacheError(message: str, *, cause: Optional[Exception] = None)

Bases: HTTPError

Raised when a cache backend (e.g. Databricks Delta table) fails to read or write a cached response.

ClientError ¶

ClientError(message: str, *, response: 'Response')

Bases: HTTPStatusError

4xx — client-side errors.

urllib3_response `property` ¶

urllib3_response

Return the bound :class:~yggdrasil.http_.HTTPResponse.

After the pool / response merge, the high-level :class:HTTPResponse carries the full urllib3-shaped surface (.status / .headers / .read / .stream / .release_conn / .drain_conn / .data) directly, so the explicit shim is gone — the response IS the shim.

to_starlette ¶

to_starlette() -> 'StarletteResponse'

Convert to a starlette.responses.JSONResponse suitable for returning directly from a Starlette or FastAPI exception handler.

The JSON body follows the RFC 7807 Problem Details shape::

{
    "status":  404,
    "error":   "Not Found",
    "detail":  "<exception message>",
    "path":    "/v1/contents/42/data",
    "method":  "GET"
}

retry_after is appended (and the Retry-After header set) when the exception carries that attribute (429 / 503).

to_fastapi ¶

to_fastapi() -> 'FastAPIJSONResponse'

Convert to a fastapi.responses.JSONResponse.

FastAPI's JSONResponse is a subclass of Starlette's, but returning the FastAPI type keeps FastAPI's exception handler machinery (background tasks, middleware hooks, OpenAPI error modelling) working correctly.

Falls back to to_starlette() transparently when FastAPI is not installed.

ClosedPoolError ¶

ClosedPoolError(message: str, *, pool: Any = None)

Bases: PoolError, ClosedPoolError

Attempted to use a connection pool that has been closed.

ConflictError ¶

ConflictError(message: str, *, response: 'Response')

Bases: ClientError

409 Conflict.

urllib3_response `property` ¶

urllib3_response

Return the bound :class:~yggdrasil.http_.HTTPResponse.

After the pool / response merge, the high-level :class:HTTPResponse carries the full urllib3-shaped surface (.status / .headers / .read / .stream / .release_conn / .drain_conn / .data) directly, so the explicit shim is gone — the response IS the shim.

to_starlette ¶

to_starlette() -> 'StarletteResponse'

Convert to a starlette.responses.JSONResponse suitable for returning directly from a Starlette or FastAPI exception handler.

The JSON body follows the RFC 7807 Problem Details shape::

{
    "status":  404,
    "error":   "Not Found",
    "detail":  "<exception message>",
    "path":    "/v1/contents/42/data",
    "method":  "GET"
}

retry_after is appended (and the Retry-After header set) when the exception carries that attribute (429 / 503).

to_fastapi ¶

to_fastapi() -> 'FastAPIJSONResponse'

Convert to a fastapi.responses.JSONResponse.

FastAPI's JSONResponse is a subclass of Starlette's, but returning the FastAPI type keeps FastAPI's exception handler machinery (background tasks, middleware hooks, OpenAPI error modelling) working correctly.

Falls back to to_starlette() transparently when FastAPI is not installed.

ConnectionError ¶

ConnectionError(message: str, *, request: 'PreparedRequest', pool: Any = None)

Bases: RequestError, NewConnectionError

Failed to open a connection to the host.

ConnectTimeoutError ¶

ConnectTimeoutError(
    message: str, *, request: "PreparedRequest", timeout: float | None = None
)

Bases: TimeoutError, ConnectTimeoutError

Timed out while establishing the TCP connection.

DecodeError ¶

DecodeError(message: str, *, response: 'Response')

Bases: ResponseError, DecodeError

Failed to decode the response body (e.g. bad gzip/zstd stream).

urllib3_response `property` ¶

urllib3_response

Return the bound :class:~yggdrasil.http_.HTTPResponse.

After the pool / response merge, the high-level :class:HTTPResponse carries the full urllib3-shaped surface (.status / .headers / .read / .stream / .release_conn / .drain_conn / .data) directly, so the explicit shim is gone — the response IS the shim.

to_starlette ¶

to_starlette() -> 'StarletteResponse'

Convert to a starlette.responses.JSONResponse suitable for returning directly from a Starlette or FastAPI exception handler.

The JSON body follows the RFC 7807 Problem Details shape::

{
    "status":  404,
    "error":   "Not Found",
    "detail":  "<exception message>",
    "path":    "/v1/contents/42/data",
    "method":  "GET"
}

retry_after is appended (and the Retry-After header set) when the exception carries that attribute (429 / 503).

to_fastapi ¶

to_fastapi() -> 'FastAPIJSONResponse'

Convert to a fastapi.responses.JSONResponse.

FastAPI's JSONResponse is a subclass of Starlette's, but returning the FastAPI type keeps FastAPI's exception handler machinery (background tasks, middleware hooks, OpenAPI error modelling) working correctly.

Falls back to to_starlette() transparently when FastAPI is not installed.

EmptyPoolError ¶

EmptyPoolError(message: str, *, pool: Any = None)

Bases: PoolError, EmptyPoolError

No connections available in the pool and block=True.

ForbiddenError ¶

ForbiddenError(message: str, *, response: 'Response')

Bases: ClientError

403 Forbidden.

urllib3_response `property` ¶

urllib3_response

Return the bound :class:~yggdrasil.http_.HTTPResponse.

After the pool / response merge, the high-level :class:HTTPResponse carries the full urllib3-shaped surface (.status / .headers / .read / .stream / .release_conn / .drain_conn / .data) directly, so the explicit shim is gone — the response IS the shim.

to_starlette ¶

to_starlette() -> 'StarletteResponse'

Convert to a starlette.responses.JSONResponse suitable for returning directly from a Starlette or FastAPI exception handler.

The JSON body follows the RFC 7807 Problem Details shape::

{
    "status":  404,
    "error":   "Not Found",
    "detail":  "<exception message>",
    "path":    "/v1/contents/42/data",
    "method":  "GET"
}

retry_after is appended (and the Retry-After header set) when the exception carries that attribute (429 / 503).

to_fastapi ¶

to_fastapi() -> 'FastAPIJSONResponse'

Convert to a fastapi.responses.JSONResponse.

FastAPI's JSONResponse is a subclass of Starlette's, but returning the FastAPI type keeps FastAPI's exception handler machinery (background tasks, middleware hooks, OpenAPI error modelling) working correctly.

Falls back to to_starlette() transparently when FastAPI is not installed.

GatewayTimeout ¶

GatewayTimeout(message: str, *, response: 'Response')

Bases: ServerError

504 Gateway Timeout.

urllib3_response `property` ¶

urllib3_response

Return the bound :class:~yggdrasil.http_.HTTPResponse.

After the pool / response merge, the high-level :class:HTTPResponse carries the full urllib3-shaped surface (.status / .headers / .read / .stream / .release_conn / .drain_conn / .data) directly, so the explicit shim is gone — the response IS the shim.

to_starlette ¶

to_starlette() -> 'StarletteResponse'

Convert to a starlette.responses.JSONResponse suitable for returning directly from a Starlette or FastAPI exception handler.

The JSON body follows the RFC 7807 Problem Details shape::

{
    "status":  404,
    "error":   "Not Found",
    "detail":  "<exception message>",
    "path":    "/v1/contents/42/data",
    "method":  "GET"
}

retry_after is appended (and the Retry-After header set) when the exception carries that attribute (429 / 503).

to_fastapi ¶

to_fastapi() -> 'FastAPIJSONResponse'

Convert to a fastapi.responses.JSONResponse.

FastAPI's JSONResponse is a subclass of Starlette's, but returning the FastAPI type keeps FastAPI's exception handler machinery (background tasks, middleware hooks, OpenAPI error modelling) working correctly.

Falls back to to_starlette() transparently when FastAPI is not installed.

GoneError ¶

GoneError(message: str, *, response: 'Response')

Bases: ClientError

410 Gone.

urllib3_response `property` ¶

urllib3_response

Return the bound :class:~yggdrasil.http_.HTTPResponse.

After the pool / response merge, the high-level :class:HTTPResponse carries the full urllib3-shaped surface (.status / .headers / .read / .stream / .release_conn / .drain_conn / .data) directly, so the explicit shim is gone — the response IS the shim.

to_starlette ¶

to_starlette() -> 'StarletteResponse'

Convert to a starlette.responses.JSONResponse suitable for returning directly from a Starlette or FastAPI exception handler.

The JSON body follows the RFC 7807 Problem Details shape::

{
    "status":  404,
    "error":   "Not Found",
    "detail":  "<exception message>",
    "path":    "/v1/contents/42/data",
    "method":  "GET"
}

retry_after is appended (and the Retry-After header set) when the exception carries that attribute (429 / 503).

to_fastapi ¶

to_fastapi() -> 'FastAPIJSONResponse'

Convert to a fastapi.responses.JSONResponse.

FastAPI's JSONResponse is a subclass of Starlette's, but returning the FastAPI type keeps FastAPI's exception handler machinery (background tasks, middleware hooks, OpenAPI error modelling) working correctly.

Falls back to to_starlette() transparently when FastAPI is not installed.

HostChangedError ¶

HostChangedError(
    message: str, *, pool: Any = None, url: str = "", retries: int = 0
)

Bases: PoolError, HostChangedError

Request was made to a different host than the pool was created for.

HTTPError ¶

Bases: YGGException, HTTPError

Root of the yggdrasil HTTP exception hierarchy.

Inherits from :class:urllib3.exceptions.HTTPError so all urllib3-aware catch blocks match, AND from :class:~yggdrasil.exceptions.YGGException so the library-wide except YGGException catches every HTTP failure too.

HTTPStatusError ¶

HTTPStatusError(message: str, *, response: 'Response')

Bases: ResponseError

Raised when the server returns a 4xx or 5xx status code.

This is the direct replacement for the old HTTPError in response.py. raise_for_status() should raise this (or a more specific subclass).

urllib3_response `property` ¶

urllib3_response

Return the bound :class:~yggdrasil.http_.HTTPResponse.

After the pool / response merge, the high-level :class:HTTPResponse carries the full urllib3-shaped surface (.status / .headers / .read / .stream / .release_conn / .drain_conn / .data) directly, so the explicit shim is gone — the response IS the shim.

to_starlette ¶

to_starlette() -> 'StarletteResponse'

Convert to a starlette.responses.JSONResponse suitable for returning directly from a Starlette or FastAPI exception handler.

The JSON body follows the RFC 7807 Problem Details shape::

{
    "status":  404,
    "error":   "Not Found",
    "detail":  "<exception message>",
    "path":    "/v1/contents/42/data",
    "method":  "GET"
}

retry_after is appended (and the Retry-After header set) when the exception carries that attribute (429 / 503).

to_fastapi ¶

to_fastapi() -> 'FastAPIJSONResponse'

Convert to a fastapi.responses.JSONResponse.

FastAPI's JSONResponse is a subclass of Starlette's, but returning the FastAPI type keeps FastAPI's exception handler machinery (background tasks, middleware hooks, OpenAPI error modelling) working correctly.

Falls back to to_starlette() transparently when FastAPI is not installed.

IncompleteRead ¶

IncompleteRead(
    message: str,
    *,
    response: "Response",
    partial: int = 0,
    expected: int | None = None
)

Bases: ResponseError, IncompleteRead

The server closed the connection before sending the full body. partial is the bytes received so far; expected is the Content-Length (None if unknown).

urllib3_response `property` ¶

urllib3_response

Return the bound :class:~yggdrasil.http_.HTTPResponse.

After the pool / response merge, the high-level :class:HTTPResponse carries the full urllib3-shaped surface (.status / .headers / .read / .stream / .release_conn / .drain_conn / .data) directly, so the explicit shim is gone — the response IS the shim.

to_starlette ¶

to_starlette() -> 'StarletteResponse'

Convert to a starlette.responses.JSONResponse suitable for returning directly from a Starlette or FastAPI exception handler.

The JSON body follows the RFC 7807 Problem Details shape::

{
    "status":  404,
    "error":   "Not Found",
    "detail":  "<exception message>",
    "path":    "/v1/contents/42/data",
    "method":  "GET"
}

retry_after is appended (and the Retry-After header set) when the exception carries that attribute (429 / 503).

to_fastapi ¶

to_fastapi() -> 'FastAPIJSONResponse'

Convert to a fastapi.responses.JSONResponse.

FastAPI's JSONResponse is a subclass of Starlette's, but returning the FastAPI type keeps FastAPI's exception handler machinery (background tasks, middleware hooks, OpenAPI error modelling) working correctly.

Falls back to to_starlette() transparently when FastAPI is not installed.

InsecureRequestWarning ¶

Bases: SecurityWarning, InsecureRequestWarning

Issued when a request is made to an HTTPS URL without cert verification.

InternalServerError ¶

InternalServerError(message: str, *, response: 'Response')

Bases: ServerError

500 Internal Server Error.

urllib3_response `property` ¶

urllib3_response

Return the bound :class:~yggdrasil.http_.HTTPResponse.

After the pool / response merge, the high-level :class:HTTPResponse carries the full urllib3-shaped surface (.status / .headers / .read / .stream / .release_conn / .drain_conn / .data) directly, so the explicit shim is gone — the response IS the shim.

to_starlette ¶

to_starlette() -> 'StarletteResponse'

Convert to a starlette.responses.JSONResponse suitable for returning directly from a Starlette or FastAPI exception handler.

The JSON body follows the RFC 7807 Problem Details shape::

{
    "status":  404,
    "error":   "Not Found",
    "detail":  "<exception message>",
    "path":    "/v1/contents/42/data",
    "method":  "GET"
}

retry_after is appended (and the Retry-After header set) when the exception carries that attribute (429 / 503).

to_fastapi ¶

to_fastapi() -> 'FastAPIJSONResponse'

Convert to a fastapi.responses.JSONResponse.

FastAPI's JSONResponse is a subclass of Starlette's, but returning the FastAPI type keeps FastAPI's exception handler machinery (background tasks, middleware hooks, OpenAPI error modelling) working correctly.

Falls back to to_starlette() transparently when FastAPI is not installed.

InvalidChunkLength ¶

InvalidChunkLength(message: str, *, response: 'Response', length: int = 0)

Bases: ResponseError, InvalidChunkLength

Received a chunked-encoding frame with an invalid length header.

urllib3_response `property` ¶

urllib3_response

Return the bound :class:~yggdrasil.http_.HTTPResponse.

After the pool / response merge, the high-level :class:HTTPResponse carries the full urllib3-shaped surface (.status / .headers / .read / .stream / .release_conn / .drain_conn / .data) directly, so the explicit shim is gone — the response IS the shim.

to_starlette ¶

to_starlette() -> 'StarletteResponse'

Convert to a starlette.responses.JSONResponse suitable for returning directly from a Starlette or FastAPI exception handler.

The JSON body follows the RFC 7807 Problem Details shape::

{
    "status":  404,
    "error":   "Not Found",
    "detail":  "<exception message>",
    "path":    "/v1/contents/42/data",
    "method":  "GET"
}

retry_after is appended (and the Retry-After header set) when the exception carries that attribute (429 / 503).

to_fastapi ¶

to_fastapi() -> 'FastAPIJSONResponse'

Convert to a fastapi.responses.JSONResponse.

FastAPI's JSONResponse is a subclass of Starlette's, but returning the FastAPI type keeps FastAPI's exception handler machinery (background tasks, middleware hooks, OpenAPI error modelling) working correctly.

Falls back to to_starlette() transparently when FastAPI is not installed.

LocationError ¶

Bases: HTTPError

Base for URL / location parse errors.

LocationParseError ¶

LocationParseError(message: str, *, location: str = '')

Bases: LocationError, LocationParseError

The URL string could not be parsed.

LocationValueError ¶

LocationValueError(message: str)

Bases: LocationError, LocationValueError

A required location component (host, port …) is missing or invalid.

MethodNotAllowed ¶

MethodNotAllowed(message: str, *, response: 'Response')

Bases: ClientError

405 Method Not Allowed.

urllib3_response `property` ¶

urllib3_response

Return the bound :class:~yggdrasil.http_.HTTPResponse.

After the pool / response merge, the high-level :class:HTTPResponse carries the full urllib3-shaped surface (.status / .headers / .read / .stream / .release_conn / .drain_conn / .data) directly, so the explicit shim is gone — the response IS the shim.

to_starlette ¶

to_starlette() -> 'StarletteResponse'

Convert to a starlette.responses.JSONResponse suitable for returning directly from a Starlette or FastAPI exception handler.

The JSON body follows the RFC 7807 Problem Details shape::

{
    "status":  404,
    "error":   "Not Found",
    "detail":  "<exception message>",
    "path":    "/v1/contents/42/data",
    "method":  "GET"
}

retry_after is appended (and the Retry-After header set) when the exception carries that attribute (429 / 503).

to_fastapi ¶

to_fastapi() -> 'FastAPIJSONResponse'

Convert to a fastapi.responses.JSONResponse.

FastAPI's JSONResponse is a subclass of Starlette's, but returning the FastAPI type keeps FastAPI's exception handler machinery (background tasks, middleware hooks, OpenAPI error modelling) working correctly.

Falls back to to_starlette() transparently when FastAPI is not installed.

NotFoundError ¶

NotFoundError(message: str, *, response: 'Response')

Bases: ClientError

404 Not Found.

urllib3_response `property` ¶

urllib3_response

Return the bound :class:~yggdrasil.http_.HTTPResponse.

After the pool / response merge, the high-level :class:HTTPResponse carries the full urllib3-shaped surface (.status / .headers / .read / .stream / .release_conn / .drain_conn / .data) directly, so the explicit shim is gone — the response IS the shim.

to_starlette ¶

to_starlette() -> 'StarletteResponse'

Convert to a starlette.responses.JSONResponse suitable for returning directly from a Starlette or FastAPI exception handler.

The JSON body follows the RFC 7807 Problem Details shape::

{
    "status":  404,
    "error":   "Not Found",
    "detail":  "<exception message>",
    "path":    "/v1/contents/42/data",
    "method":  "GET"
}

retry_after is appended (and the Retry-After header set) when the exception carries that attribute (429 / 503).

to_fastapi ¶

to_fastapi() -> 'FastAPIJSONResponse'

Convert to a fastapi.responses.JSONResponse.

FastAPI's JSONResponse is a subclass of Starlette's, but returning the FastAPI type keeps FastAPI's exception handler machinery (background tasks, middleware hooks, OpenAPI error modelling) working correctly.

Falls back to to_starlette() transparently when FastAPI is not installed.

PoolError ¶

Bases: HTTPError

Base for connection-pool errors (no request/response yet).

ProxyError ¶

ProxyError(
    message: str,
    *,
    request: "PreparedRequest",
    original_error: Optional[Exception] = None
)

Bases: RequestError, ProxyError

Error communicating through a proxy.

ReadTimeoutError ¶

ReadTimeoutError(
    message: str,
    *,
    request: "PreparedRequest",
    timeout: float | None = None,
    pool: Any = None,
    url: str | None = None
)

Bases: TimeoutError, ReadTimeoutError

Timed out while reading the response body.

RequestError ¶

RequestError(message: str, *, request: 'PreparedRequest')

Bases: HTTPError

Base for errors that occur before/during sending a request, when no Response is available yet.

ResponseError ¶

ResponseError(message: str, *, response: 'Response')

Bases: HTTPError

Base for errors where a Response has been received. Always carries both response and request (via response.request).

urllib3_response `property` ¶

urllib3_response

Return the bound :class:~yggdrasil.http_.HTTPResponse.

After the pool / response merge, the high-level :class:HTTPResponse carries the full urllib3-shaped surface (.status / .headers / .read / .stream / .release_conn / .drain_conn / .data) directly, so the explicit shim is gone — the response IS the shim.

to_starlette ¶

to_starlette() -> 'StarletteResponse'

Convert to a starlette.responses.JSONResponse suitable for returning directly from a Starlette or FastAPI exception handler.

The JSON body follows the RFC 7807 Problem Details shape::

{
    "status":  404,
    "error":   "Not Found",
    "detail":  "<exception message>",
    "path":    "/v1/contents/42/data",
    "method":  "GET"
}

retry_after is appended (and the Retry-After header set) when the exception carries that attribute (429 / 503).

to_fastapi ¶

to_fastapi() -> 'FastAPIJSONResponse'

Convert to a fastapi.responses.JSONResponse.

FastAPI's JSONResponse is a subclass of Starlette's, but returning the FastAPI type keeps FastAPI's exception handler machinery (background tasks, middleware hooks, OpenAPI error modelling) working correctly.

Falls back to to_starlette() transparently when FastAPI is not installed.

SecurityWarning ¶

Bases: Warning

Issued for insecure connections or weak TLS configurations.

ServerError ¶

ServerError(message: str, *, response: 'Response')

Bases: HTTPStatusError

5xx — server-side errors.

urllib3_response `property` ¶

urllib3_response

Return the bound :class:~yggdrasil.http_.HTTPResponse.

After the pool / response merge, the high-level :class:HTTPResponse carries the full urllib3-shaped surface (.status / .headers / .read / .stream / .release_conn / .drain_conn / .data) directly, so the explicit shim is gone — the response IS the shim.

to_starlette ¶

to_starlette() -> 'StarletteResponse'

Convert to a starlette.responses.JSONResponse suitable for returning directly from a Starlette or FastAPI exception handler.

The JSON body follows the RFC 7807 Problem Details shape::

{
    "status":  404,
    "error":   "Not Found",
    "detail":  "<exception message>",
    "path":    "/v1/contents/42/data",
    "method":  "GET"
}

retry_after is appended (and the Retry-After header set) when the exception carries that attribute (429 / 503).

to_fastapi ¶

to_fastapi() -> 'FastAPIJSONResponse'

Convert to a fastapi.responses.JSONResponse.

FastAPI's JSONResponse is a subclass of Starlette's, but returning the FastAPI type keeps FastAPI's exception handler machinery (background tasks, middleware hooks, OpenAPI error modelling) working correctly.

Falls back to to_starlette() transparently when FastAPI is not installed.

ServiceUnavailable ¶

ServiceUnavailable(message: str, *, response: 'Response')

Bases: ServerError

503 Service Unavailable.

Carries retry_after when present.

urllib3_response `property` ¶

urllib3_response

Return the bound :class:~yggdrasil.http_.HTTPResponse.

After the pool / response merge, the high-level :class:HTTPResponse carries the full urllib3-shaped surface (.status / .headers / .read / .stream / .release_conn / .drain_conn / .data) directly, so the explicit shim is gone — the response IS the shim.

to_starlette ¶

to_starlette() -> 'StarletteResponse'

Convert to a starlette.responses.JSONResponse suitable for returning directly from a Starlette or FastAPI exception handler.

The JSON body follows the RFC 7807 Problem Details shape::

{
    "status":  404,
    "error":   "Not Found",
    "detail":  "<exception message>",
    "path":    "/v1/contents/42/data",
    "method":  "GET"
}

retry_after is appended (and the Retry-After header set) when the exception carries that attribute (429 / 503).

to_fastapi ¶

to_fastapi() -> 'FastAPIJSONResponse'

Convert to a fastapi.responses.JSONResponse.

FastAPI's JSONResponse is a subclass of Starlette's, but returning the FastAPI type keeps FastAPI's exception handler machinery (background tasks, middleware hooks, OpenAPI error modelling) working correctly.

Falls back to to_starlette() transparently when FastAPI is not installed.

SSLError ¶

SSLError(message: str, *, response: 'Response')

Bases: ResponseError, SSLError

TLS/SSL handshake or certificate validation failure.

urllib3_response `property` ¶

urllib3_response

Return the bound :class:~yggdrasil.http_.HTTPResponse.

After the pool / response merge, the high-level :class:HTTPResponse carries the full urllib3-shaped surface (.status / .headers / .read / .stream / .release_conn / .drain_conn / .data) directly, so the explicit shim is gone — the response IS the shim.

to_starlette ¶

to_starlette() -> 'StarletteResponse'

Convert to a starlette.responses.JSONResponse suitable for returning directly from a Starlette or FastAPI exception handler.

The JSON body follows the RFC 7807 Problem Details shape::

{
    "status":  404,
    "error":   "Not Found",
    "detail":  "<exception message>",
    "path":    "/v1/contents/42/data",
    "method":  "GET"
}

retry_after is appended (and the Retry-After header set) when the exception carries that attribute (429 / 503).

to_fastapi ¶

to_fastapi() -> 'FastAPIJSONResponse'

Convert to a fastapi.responses.JSONResponse.

FastAPI's JSONResponse is a subclass of Starlette's, but returning the FastAPI type keeps FastAPI's exception handler machinery (background tasks, middleware hooks, OpenAPI error modelling) working correctly.

Falls back to to_starlette() transparently when FastAPI is not installed.

TimeoutError ¶

TimeoutError(
    message: str, *, request: "PreparedRequest", timeout: float | None = None
)

Bases: RequestError, TimeoutError

Base for all timeout variants.

TooManyRequests ¶

TooManyRequests(message: str, *, response: 'Response')

Bases: ClientError

429 Too Many Requests.

Carries retry_after (seconds) when the upstream Retry-After header is present and parseable.

urllib3_response `property` ¶

urllib3_response

Return the bound :class:~yggdrasil.http_.HTTPResponse.

After the pool / response merge, the high-level :class:HTTPResponse carries the full urllib3-shaped surface (.status / .headers / .read / .stream / .release_conn / .drain_conn / .data) directly, so the explicit shim is gone — the response IS the shim.

to_starlette ¶

to_starlette() -> 'StarletteResponse'

Convert to a starlette.responses.JSONResponse suitable for returning directly from a Starlette or FastAPI exception handler.

The JSON body follows the RFC 7807 Problem Details shape::

{
    "status":  404,
    "error":   "Not Found",
    "detail":  "<exception message>",
    "path":    "/v1/contents/42/data",
    "method":  "GET"
}

retry_after is appended (and the Retry-After header set) when the exception carries that attribute (429 / 503).

to_fastapi ¶

to_fastapi() -> 'FastAPIJSONResponse'

Convert to a fastapi.responses.JSONResponse.

FastAPI's JSONResponse is a subclass of Starlette's, but returning the FastAPI type keeps FastAPI's exception handler machinery (background tasks, middleware hooks, OpenAPI error modelling) working correctly.

Falls back to to_starlette() transparently when FastAPI is not installed.

UnauthorizedError ¶

UnauthorizedError(message: str, *, response: 'Response')

Bases: ClientError

401 Unauthorized.

urllib3_response `property` ¶

urllib3_response

Return the bound :class:~yggdrasil.http_.HTTPResponse.

After the pool / response merge, the high-level :class:HTTPResponse carries the full urllib3-shaped surface (.status / .headers / .read / .stream / .release_conn / .drain_conn / .data) directly, so the explicit shim is gone — the response IS the shim.

to_starlette ¶

to_starlette() -> 'StarletteResponse'

Convert to a starlette.responses.JSONResponse suitable for returning directly from a Starlette or FastAPI exception handler.

The JSON body follows the RFC 7807 Problem Details shape::

{
    "status":  404,
    "error":   "Not Found",
    "detail":  "<exception message>",
    "path":    "/v1/contents/42/data",
    "method":  "GET"
}

retry_after is appended (and the Retry-After header set) when the exception carries that attribute (429 / 503).

to_fastapi ¶

to_fastapi() -> 'FastAPIJSONResponse'

Convert to a fastapi.responses.JSONResponse.

FastAPI's JSONResponse is a subclass of Starlette's, but returning the FastAPI type keeps FastAPI's exception handler machinery (background tasks, middleware hooks, OpenAPI error modelling) working correctly.

Falls back to to_starlette() transparently when FastAPI is not installed.

UnprocessableEntity ¶

UnprocessableEntity(message: str, *, response: 'Response')

Bases: ClientError

422 Unprocessable Entity.

urllib3_response `property` ¶

urllib3_response

Return the bound :class:~yggdrasil.http_.HTTPResponse.

After the pool / response merge, the high-level :class:HTTPResponse carries the full urllib3-shaped surface (.status / .headers / .read / .stream / .release_conn / .drain_conn / .data) directly, so the explicit shim is gone — the response IS the shim.

to_starlette ¶

to_starlette() -> 'StarletteResponse'

Convert to a starlette.responses.JSONResponse suitable for returning directly from a Starlette or FastAPI exception handler.

The JSON body follows the RFC 7807 Problem Details shape::

{
    "status":  404,
    "error":   "Not Found",
    "detail":  "<exception message>",
    "path":    "/v1/contents/42/data",
    "method":  "GET"
}

retry_after is appended (and the Retry-After header set) when the exception carries that attribute (429 / 503).

to_fastapi ¶

to_fastapi() -> 'FastAPIJSONResponse'

Convert to a fastapi.responses.JSONResponse.

FastAPI's JSONResponse is a subclass of Starlette's, but returning the FastAPI type keeps FastAPI's exception handler machinery (background tasks, middleware hooks, OpenAPI error modelling) working correctly.

Falls back to to_starlette() transparently when FastAPI is not installed.

register_api_exception_handlers ¶

register_api_exception_handlers(app: 'FastAPI') -> None

Wire :class:APIError into a FastAPI app's exception handling.

from_urllib3 ¶

from_urllib3(
    exc: HTTPError,
    *,
    request: Optional["PreparedRequest"] = None,
    response: Optional["Response"] = None
) -> "HTTPError"

Wrap an arbitrary urllib3.exceptions.HTTPError in the yggdrasil hierarchy, preserving the original as __cause__.

Useful in HTTP adapter layers that catch raw urllib3 errors and need to re-raise them with richer context.

Example¶

try: ... pool.urlopen(...) ... except urllib3.exceptions.TimeoutError as e: ... raise from_urllib3(e, request=req) from e

make_for_status ¶

make_for_status(
    response: "Response", *, max_body: int = 2048
) -> Optional["HTTPError"]

Raise the most specific HTTPStatusError subclass for 4xx/5xx responses. No-op for 1xx/2xx/3xx.

Replaces Response.raise_for_status() — call this as a free function or keep the method as a thin wrapper.

Example¶

error = make_for_status(response)

yggdrasil.exceptions¶

exceptions ¶

APIError ¶

BadRequestError ¶

APIConflictError ¶

APIForbiddenError ¶

MethodNotAllowedError ¶

APINotFoundError ¶

APITimeoutError ¶

TooManyRequestsError ¶

APIUnauthorizedError ¶

UnprocessableError ¶

YGGException ¶

CastError ¶

LokiError ¶

TokenBudgetExceeded ¶

AuthRequiredError ¶

BadGatewayError ¶

urllib3_response property ¶

to_starlette ¶

to_fastapi ¶

BadRequest ¶

urllib3_response property ¶

to_starlette ¶

to_fastapi ¶

CacheError ¶

ClientError ¶

urllib3_response property ¶

to_starlette ¶

to_fastapi ¶

ClosedPoolError ¶

ConflictError ¶

urllib3_response property ¶

to_starlette ¶

to_fastapi ¶

ConnectionError ¶

ConnectTimeoutError ¶

DecodeError ¶

urllib3_response property ¶

to_starlette ¶

to_fastapi ¶

EmptyPoolError ¶

ForbiddenError ¶

urllib3_response property ¶

to_starlette ¶

to_fastapi ¶

GatewayTimeout ¶

urllib3_response property ¶

to_starlette ¶

to_fastapi ¶

GoneError ¶

urllib3_response property ¶

to_starlette ¶

to_fastapi ¶

HostChangedError ¶

HTTPError ¶

HTTPStatusError ¶

urllib3_response property ¶

to_starlette ¶

to_fastapi ¶

IncompleteRead ¶

urllib3_response property ¶

to_starlette ¶

to_fastapi ¶

InsecureRequestWarning ¶

InternalServerError ¶

urllib3_response property ¶

to_starlette ¶

to_fastapi ¶

InvalidChunkLength ¶

urllib3_response property ¶

to_starlette ¶

to_fastapi ¶

LocationError ¶

LocationParseError ¶

LocationValueError ¶

MethodNotAllowed ¶

urllib3_response property ¶

to_starlette ¶

to_fastapi ¶

`yggdrasil.exceptions`¶

urllib3_response `property` ¶

urllib3_response `property` ¶

urllib3_response `property` ¶

urllib3_response `property` ¶

urllib3_response `property` ¶

urllib3_response `property` ¶

urllib3_response `property` ¶

urllib3_response `property` ¶

urllib3_response `property` ¶

urllib3_response `property` ¶

urllib3_response `property` ¶

urllib3_response `property` ¶

urllib3_response `property` ¶

urllib3_response `property` ¶

urllib3_response `property` ¶

urllib3_response `property` ¶

urllib3_response `property` ¶

urllib3_response `property` ¶

urllib3_response `property` ¶

urllib3_response `property` ¶

urllib3_response `property` ¶