`yggdrasil.exceptions.http`¶

http ¶

HTTP exception hierarchy — lives under :mod:yggdrasil.exceptions.

Every type defined here subclasses :class:YGGException through :class:HTTPError, so a generic except YGGException catches every error the library deliberately raises (HTTP-bound included, alongside :class:CastError and any future global type). Keeping the hierarchy at the package root (and not under io/) means non-IO modules can raise NotFoundError(...) / raise ForbiddenError(...) / raise TooManyRequests(...) without pulling :mod:yggdrasil.io first; see AGENTS.md → "Centralise exceptions in :mod:yggdrasil.exceptions" for the rule.

The hierarchy also:

Inherits from the stdlib-backed transport exceptions in :mod:yggdrasil.http_.exceptions (urllib3-shaped, but stdlib-only) so transport-level except blocks still match across the transport/business boundary.
Carries a bound Response (and/or PreparedRequest) on every exception so callers never need to thread response objects through manually.
Mirrors the public transport exceptions that have HTTP-level semantics, adding typed response / request attributes where applicable.

Hierarchy (transport exceptions sourced from :mod:yggdrasil.http_.exceptions; additions marked with *): ───────────────────────────────────────────────────── HTTPError ← _http_pool.HTTPError ├── RequestError * ← request-bound base │ ├── ConnectionError ← _http_pool.NewConnectionError │ ├── TimeoutError ← _http_pool.TimeoutError │ │ ├── ConnectTimeoutError │ │ └── ReadTimeoutError │ └── ProxyError ← _http_pool.ProxyError │ ├── ResponseError * ← response-bound base │ ├── HTTPStatusError * ← 4xx / 5xx (was HTTPError in response.py) │ │ ├── ClientError ← 4xx │ │ │ ├── BadRequest (400) │ │ │ ├── UnauthorizedError (401) │ │ │ ├── ForbiddenError (403) │ │ │ ├── NotFoundError (404) │ │ │ ├── MethodNotAllowed (405) │ │ │ ├── ConflictError (409) │ │ │ ├── GoneError (410) │ │ │ ├── UnprocessableEntity (422) │ │ │ ├── TooManyRequests (429) │ │ └── ServerError ← 5xx │ │ ├── InternalServerError (500) │ │ ├── BadGatewayError (502) │ │ ├── ServiceUnavailable (503) │ │ └── GatewayTimeout (504) │ ├── DecodeError ← _http_pool.DecodeError │ ├── InvalidChunkLength ← _http_pool.InvalidChunkLength │ └── IncompleteRead ← _http_pool.IncompleteRead │ ├── PoolError * ← _http_pool.PoolError │ ├── ClosedPoolError ← _http_pool.ClosedPoolError │ ├── EmptyPoolError ← _http_pool.EmptyPoolError │ └── HostChangedError ← _http_pool.HostChangedError │ ├── LocationError * │ ├── LocationValueError ← _http_pool.LocationValueError │ └── LocationParseError ← _http_pool.LocationParseError │ ├── SecurityWarning (Warning) ← _http_pool.SecurityWarning ├── InsecureRequestWarning ← _http_pool.InsecureRequestWarning ├── SSLError ← _http_pool.SSLError └── CacheError * ← cache backend failures

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.

RequestError ¶

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

Bases: HTTPError

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

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).

ConnectionError ¶

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

Bases: RequestError, NewConnectionError

Failed to open a connection to the host.

TimeoutError ¶

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

Bases: RequestError, TimeoutError

Base for all timeout variants.

ConnectTimeoutError ¶

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

Bases: TimeoutError, ConnectTimeoutError

Timed out while establishing the TCP connection.

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.

ProxyError ¶

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

Bases: RequestError, ProxyError

Error communicating through a proxy.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

PoolError ¶

Bases: HTTPError

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

ClosedPoolError ¶

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

Bases: PoolError, ClosedPoolError

Attempted to use a connection pool that has been closed.

EmptyPoolError ¶

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

Bases: PoolError, EmptyPoolError

No connections available in the pool and block=True.

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.

LocationError ¶

Bases: HTTPError

Base for URL / location parse errors.

LocationValueError ¶

LocationValueError(message: str)

Bases: LocationError, LocationValueError

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

LocationParseError ¶

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

Bases: LocationError, LocationParseError

The URL string could not be parsed.

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.

SecurityWarning ¶

Bases: Warning

Issued for insecure connections or weak TLS configurations.

InsecureRequestWarning ¶

Bases: SecurityWarning, InsecureRequestWarning

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

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.

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)

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

yggdrasil.exceptions.http¶

http ¶

HTTPError ¶

RequestError ¶

AuthRequiredError ¶

ConnectionError ¶

TimeoutError ¶

ConnectTimeoutError ¶

ReadTimeoutError ¶

ProxyError ¶

ResponseError ¶

urllib3_response property ¶

to_starlette ¶

to_fastapi ¶

HTTPStatusError ¶

urllib3_response property ¶

to_starlette ¶

to_fastapi ¶

ClientError ¶

urllib3_response property ¶

to_starlette ¶

to_fastapi ¶

ServerError ¶

urllib3_response property ¶

to_starlette ¶

to_fastapi ¶

BadRequest ¶

urllib3_response property ¶

to_starlette ¶

to_fastapi ¶

UnauthorizedError ¶

urllib3_response property ¶

to_starlette ¶

to_fastapi ¶

ForbiddenError ¶

urllib3_response property ¶

to_starlette ¶

to_fastapi ¶

NotFoundError ¶

urllib3_response property ¶

to_starlette ¶

to_fastapi ¶

MethodNotAllowed ¶

urllib3_response property ¶

to_starlette ¶

to_fastapi ¶

ConflictError ¶

urllib3_response property ¶

to_starlette ¶

to_fastapi ¶

GoneError ¶

urllib3_response property ¶

to_starlette ¶

to_fastapi ¶

UnprocessableEntity ¶

urllib3_response property ¶

to_starlette ¶

to_fastapi ¶

TooManyRequests ¶

urllib3_response property ¶

to_starlette ¶

to_fastapi ¶

InternalServerError ¶

urllib3_response property ¶

to_starlette ¶

to_fastapi ¶

BadGatewayError ¶

urllib3_response property ¶

to_starlette ¶

to_fastapi ¶

ServiceUnavailable ¶

urllib3_response property ¶

to_starlette ¶

to_fastapi ¶

GatewayTimeout ¶

urllib3_response property ¶

to_starlette ¶

to_fastapi ¶

DecodeError ¶

urllib3_response property ¶

`yggdrasil.exceptions.http`¶

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` ¶