Skip to content

aiollm.http

http

Transport-neutral HTTP primitives: API, auth, headers and errors.

Modules:

Name Description
api

Default IAPI implementation.

auth

Request authentication: bearer token and API key.

exceptions

HTTP and transport errors and the error resolver.

headers

Header names and values used by the library, and header parsing.

protocols

Interfaces of the HTTP primitives: API location, auth and headers.

Type Aliases:

Name Description
HeadersType

Headers given as a mapping or as an IHeaders collection.

Query

Query parameters; a list is sent as a repeated key.

Classes:

Name Description
BaseAPI

Builds request URLs from a root URL and a version segment.

APIKeyAuth

Sends the key as is, in the header named header_name.

BearerAuth

Sends the token as Authorization: Bearer <token>.

Headers

Case-insensitive collection of default request headers.

IAPI

Builds request URLs for one API.

IAuth

Produces the authentication header of every request.

IHeaders

Default headers the session sends with every request.

HeadersType

HeadersType = HeadersMapping | IHeaders

Headers given as a mapping or as an IHeaders collection.

Query

Query = Mapping[str, str | list[str]]

Query parameters; a list is sent as a repeated key.

BaseAPI

BaseAPI(base_url: str | URL, version: str)

Builds request URLs from a root URL and a version segment.

Attributes:

Name Type Description
base_url

Root URL of the API; it may end with a path prefix.

version

API version segment, e.g. "v1"; empty for none.

Example

api = BaseAPI("https://api.example.com", "v1") api.build_url("/models/m%2F1", {"limit": "5"}) 'https://api.example.com/v1/models/m%2F1?limit=5'

Create the API description.

Parameters:

Name Type Description Default
base_url str | URL

Root URL, e.g. "https://api.example.com".

required
version str

API version segment, e.g. "v1".

required

Raises:

Type Description
ValueError

If base_url is not an absolute HTTP(S) URL or has a query or fragment, or version is not one path segment.

Methods:

Name Description
build_url

Build the absolute URL for a request.

build_url

build_url(method: str, query: Query | None = None) -> str

Build the absolute URL for a request.

Parameters:

Name Type Description Default
method str

Request path of the method, already percent-encoded; it is joined without encoding it again.

required
query Query | None

Query parameters, not encoded yet; a list value becomes a repeated key.

None

Returns:

Type Description
str

The absolute URL to request.

APIKeyAuth dataclass

APIKeyAuth(key: str, header_name: str = X_API_KEY)

Sends the key as is, in the header named header_name.

Example

auth = APIKeyAuth("sk-...") # for an X-Api-Key provider auth.header_name, auth.encode() ('X-Api-Key', 'sk-...')

Attributes:

Name Type Description
key str

The API key. Excluded from repr so it does not leak into logs.

header_name str

Name of the header that carries the key.

Methods:

Name Description
encode

Return the header value.

encode

encode() -> str

Return the header value.

Returns:

Type Description
str

The key itself.

BearerAuth dataclass

BearerAuth(token: str)

Sends the token as Authorization: Bearer <token>.

Attributes:

Name Type Description
token str

The API key or access token. Excluded from repr so it does not leak into logs.

Methods:

Name Description
encode

Return the Authorization header value.

header_name property

header_name: str

Name of the header: Authorization.

encode

encode() -> str

Return the Authorization header value.

Returns:

Type Description
str

"Bearer <token>".

Headers

Headers(headers: HeadersType | None = None)

Case-insensitive collection of default request headers.

Attributes:

Name Type Description
headers

The stored headers.

Create the collection.

Parameters:

Name Type Description Default
headers HeadersType | None

Initial headers, as a mapping or another collection, which is copied.

None

Methods:

Name Description
add

Add or replace headers.

copy

Return an independent copy of the stored headers.

build

Return the stored headers merged with extra.

add

add(headers: HeadersType) -> None

Add or replace headers.

Parameters:

Name Type Description Default
headers HeadersType

Headers to merge in, as a mapping or a collection; existing names are overwritten.

required

copy

copy() -> HeadersDict

Return an independent copy of the stored headers.

Returns:

Type Description
HeadersDict

A new case-insensitive mapping.

build

build(extra: HeadersType | None = None) -> HeadersDict

Return the stored headers merged with extra.

The collection itself is not modified.

Parameters:

Name Type Description Default
extra HeadersType | None

Headers that take precedence over the stored ones, as a mapping or a collection; None for none.

None

Returns:

Type Description
HeadersDict

A new case-insensitive mapping.

IAPI

Bases: Protocol

Builds request URLs for one API.

Implemented once per provider; the session asks it for the full URL of every request.

Attributes:

Name Type Description
base_url URL

Root URL of the API, e.g. https://api.example.com.

version str

API version segment, e.g. "v1".

Methods:

Name Description
build_url

Build the absolute URL for a request.

build_url

build_url(method: str, query: Query | None = None) -> str

Build the absolute URL for a request.

Parameters:

Name Type Description Default
method str

Request path of the method, e.g. "/models/m%2F1". It is already percent-encoded and must not be encoded again: join it with URL.joinpath(..., encoded=True), not with yarl's / operator, which would turn %2F into %252F.

required
query Query | None

Query parameters to append, already converted to strings, not encoded yet; a list value becomes a repeated key (ids=a&ids=b).

None

Returns:

Type Description
str

The absolute URL to request.

IAuth

Bases: Protocol

Produces the authentication header of every request.

Methods:

Name Description
encode

Return the header value.

Attributes:

Name Type Description
header_name str

Name of the header, such as Authorization or x-api-key.

header_name property

header_name: str

Name of the header, such as Authorization or x-api-key.

encode

encode() -> str

Return the header value.

Returns:

Type Description
str

The full header value, including the scheme if any.

IHeaders

Bases: Protocol

Default headers the session sends with every request.

Methods:

Name Description
add

Add or replace headers.

copy

Return an independent copy of the stored headers.

build

Return the stored headers merged with extra.

Attributes:

Name Type Description
headers HeadersDict

The stored headers.

headers property

headers: HeadersDict

The stored headers.

add

add(headers: HeadersType) -> None

Add or replace headers.

Parameters:

Name Type Description Default
headers HeadersType

Headers to merge in, as a mapping or a collection.

required

copy

copy() -> HeadersDict

Return an independent copy of the stored headers.

Returns:

Type Description
HeadersDict

A new case-insensitive mapping.

build

build(extra: HeadersType | None = None) -> HeadersDict

Return the stored headers merged with extra.

Parameters:

Name Type Description Default
extra HeadersType | None

Headers that take precedence over the stored ones; None for none.

None

Returns:

Type Description
HeadersDict

A new case-insensitive mapping.

exceptions

HTTP and transport errors and the error resolver.

Modules:

Name Description
aiohttp

Translation of aiohttp exceptions into library errors.

protocols

Interface for turning HTTP error responses into exceptions.

resolver

Default mapping of HTTP error responses to APIStatusError classes.

response

Errors for responses that arrived but cannot be used.

status

Errors for HTTP responses with an error status code.

transport

Errors raised when no valid HTTP response could be obtained.

Classes:

Name Description
IErrorResolver

Creates the APIStatusError for a response with an error status.

BaseErrorResolver

Turns an HTTP error response into an APIStatusError.

APIResponseError

A response was received but its body could not be used.

APIStatusError

The API reported a failure: an error status or an in-band error.

AuthenticationError

HTTP 401: the credentials are missing or invalid.

BadGatewayError

HTTP 502: an upstream server returned an invalid response.

BadRequestError

HTTP 400: the request parameters are invalid.

BillingError

HTTP 402: payment is required.

ConflictError

HTTP 409: the request conflicts with the resource state.

ContentTooLargeError

HTTP 413: the request is larger than the API accepts (RFC 9110).

GatewayTimeoutError

HTTP 504: an upstream server did not respond in time.

InternalServerError

HTTP 500: the API failed unexpectedly.

NotFoundError

HTTP 404: the resource does not exist.

PermissionDeniedError

HTTP 403: the credentials lack the required permissions.

QuotaExceededError

The account's credits or usage limits are exhausted.

RateLimitError

HTTP 429: too many requests or tokens.

RequestTimeoutError

HTTP 408: the server timed out waiting for the request.

ServiceUnavailableError

HTTP 503: the API is temporarily unavailable.

UnprocessableEntityError

HTTP 422: the request is well-formed but semantically invalid.

APIConnectionError

The connection could not be established or was lost.

APIRedirectError

A redirect was not followed; retrying will not help.

APIRequestError

The request itself cannot be sent; retrying will not help.

APIStreamInterruptedError

An open stream broke or ended before it was complete.

APITimeoutError

The request or a read from the stream exceeded its timeout.

APITLSError

TLS verification failed; retrying will not help.

APITransportError

The request failed below the HTTP layer.

Attributes:

Name Type Description
HTTP_ERRORS Final[dict[int, type[APIStatusError]]]

Error class to raise for each known HTTP status code.

HTTP_ERRORS module-attribute

Error class to raise for each known HTTP status code.

IErrorResolver

Bases: Protocol

Creates the APIStatusError for a response with an error status.

Methods:

Name Description
resolve

Build the error for a failed response.

resolve

resolve(
    *, status: int, body: Any, headers: Mapping[str, str]
) -> APIStatusError

Build the error for a failed response.

Parameters:

Name Type Description Default
status int

HTTP status code, 400 or higher; for an error event inside a stream, the status of the stream itself.

required
body Any

Decoded JSON body, or None if it was not valid JSON.

required
headers Mapping[str, str]

Response headers.

required

Returns:

Type Description
APIStatusError

The error for the session to raise.

BaseErrorResolver

Turns an HTTP error response into an APIStatusError.

The body is expected in the common {"error": {"code", "type", "message"}} shape; a string error (as Ollama sends) is taken as the message. Provider-specific resolvers subclass this and set provider and error_statuses, and override get_error_code or classify_status where the provider differs.

A failure reported with a status below 400 (a stream's error event, a result that says it failed) is in-band: it is classified by the status error_statuses gives its code, else its type, and it is never transient, whatever its class. The generation ran and failed; running it again is the caller's choice, as in the official SDKs, which retry by the HTTP status only.

Attributes:

Name Type Description
provider Provider

Provider recorded on the created errors.

error_statuses Mapping[str, int]

HTTP status that each in-band error code or type stands for; empty by default.

Methods:

Name Description
resolve

Build the error for a failed response.

get_error_code

Extract the provider error code from the error object.

classify

Choose the error class and whether the error is transient.

classify_status

Choose the error class and transience of an HTTP status.

resolve

resolve(
    *, status: int, body: Any, headers: Mapping[str, str]
) -> APIStatusError

Build the error for a failed response.

Parameters:

Name Type Description Default
status int

HTTP status code of the response.

required
body Any

Decoded JSON body, or None if it was not valid JSON.

required
headers Mapping[str, str]

Response headers.

required

Returns:

Type Description
APIStatusError

The error to raise; it is returned, not raised, so the caller

APIStatusError

controls the traceback.

get_error_code

get_error_code(error: Mapping[str, Any]) -> str | None

Extract the provider error code from the error object.

Parameters:

Name Type Description Default
error Mapping[str, Any]

The error object of the response body.

required

Returns:

Type Description
str | None

The error code, or None if there is none.

classify

classify(
    *,
    status: int,
    code: str | None,
    error_type: str | None,
    message: str | None,
    retry_after: float | None,
) -> tuple[type[APIStatusError], bool]

Choose the error class and whether the error is transient.

An in-band failure (a status below 400) is first given the status error_statuses lists for its code, else for its type, and is never transient; then classify_status decides.

Parameters:

Name Type Description Default
status int

HTTP status code of the response.

required
code str | None

Provider error code.

required
error_type str | None

Provider error type.

required
message str | None

Provider error message.

required
retry_after float | None

Seconds from the Retry-After header.

required

Returns:

Type Description
type[APIStatusError]

The APIStatusError subclass to instantiate and the

bool

transient flag.

classify_status

classify_status(
    *,
    status: int,
    code: str | None,
    error_type: str | None,
    message: str | None,
    retry_after: float | None,
) -> tuple[type[APIStatusError], bool]

Choose the error class and transience of an HTTP status.

The default maps the status through HTTP_ERRORS and treats timeouts and server errors (TRANSIENT_STATUSES) as transient, and 429 (rate limit) when the API said when to retry. A provider overrides it for its own codes; classify keeps an in-band failure non-transient whatever it returns.

Parameters:

Name Type Description Default
status int

HTTP status code, for an in-band failure the one its code or type stands for.

required
code str | None

Provider error code.

required
error_type str | None

Provider error type.

required
message str | None

Provider error message.

required
retry_after float | None

Seconds from the Retry-After header.

required

Returns:

Type Description
type[APIStatusError]

The APIStatusError subclass to instantiate and the

bool

transient flag.

APIResponseError

APIResponseError(
    message: str, *, status: int | None = None
)

Bases: AIAPIError

A response was received but its body could not be used.

Raised when the response is not valid HTTP, its body is larger than the session accepts, or the body cannot be decoded or validated against the method's response model, or a stream breaks its protocol (an item after its terminal event). It is never retried; a body cut off by a lost connection is an APIConnectionError instead, and an APIStreamInterruptedError while a stream is iterated.

Attributes:

Name Type Description
status

HTTP status code of the response, if known.

Store the message and the response status.

Parameters:

Name Type Description Default
message str

Description of the failure.

required
status int | None

HTTP status code of the response.

None

APIStatusError

APIStatusError(
    *,
    status: int,
    message: str | None = None,
    code: str | None = None,
    error_type: str | None = None,
    provider: Provider = GENERIC,
    request_id: str | None = None,
    retry_after: float | None = None,
    transient: bool = False,
    raw: Any = None,
)

Bases: AIAPIError

The API reported a failure: an error status or an in-band error.

Raised for a response with a status code of 400 or higher, and also for a failure the API reports after a successful status: an error event of a stream or a result that says it failed, such as OpenAI's Response with status failed. Instances are created by an error resolver from the response status, headers and body; subclasses in HTTP_ERRORS narrow it down by status code (for an in-band failure, by the status its code stands for).

Attributes:

Name Type Description
status

HTTP status code of the response; the successful status of the stream or the response for an in-band failure.

code

Provider-specific error code, if the body carried one.

error_type

Provider-specific error type, if the body carried one.

provider

Provider that produced the error.

request_id

Request id from the response headers or body, useful when contacting the provider's support.

retry_after

Seconds to wait before retrying, from the Retry-After header.

transient

Whether retrying the same request may succeed. This is the only flag the retry strategy looks at.

raw

The parsed result that reported the failure, when a successful response or a stream event did: OpenAI's Response with status failed, or its response.failed event. None for an error status and for events that do not fit the item type.

Store the error details.

Parameters:

Name Type Description Default
status int

HTTP status code of the response.

required
message str | None

Error message reported by the API.

None
code str | None

Provider-specific error code.

None
error_type str | None

Provider-specific error type.

None
provider Provider

Provider that produced the error.

GENERIC
request_id str | None

Request id of the failed request.

None
retry_after float | None

Seconds to wait before retrying.

None
transient bool

Whether the request may be retried.

False
raw Any

The parsed result that reported the failure, if any.

None

AuthenticationError

AuthenticationError(
    *,
    status: int,
    message: str | None = None,
    code: str | None = None,
    error_type: str | None = None,
    provider: Provider = GENERIC,
    request_id: str | None = None,
    retry_after: float | None = None,
    transient: bool = False,
    raw: Any = None,
)

Bases: APIStatusError

HTTP 401: the credentials are missing or invalid.

BadGatewayError

BadGatewayError(
    *,
    status: int,
    message: str | None = None,
    code: str | None = None,
    error_type: str | None = None,
    provider: Provider = GENERIC,
    request_id: str | None = None,
    retry_after: float | None = None,
    transient: bool = False,
    raw: Any = None,
)

Bases: APIStatusError

HTTP 502: an upstream server returned an invalid response.

BadRequestError

BadRequestError(
    *,
    status: int,
    message: str | None = None,
    code: str | None = None,
    error_type: str | None = None,
    provider: Provider = GENERIC,
    request_id: str | None = None,
    retry_after: float | None = None,
    transient: bool = False,
    raw: Any = None,
)

Bases: APIStatusError

HTTP 400: the request parameters are invalid.

BillingError

BillingError(
    *,
    status: int,
    message: str | None = None,
    code: str | None = None,
    error_type: str | None = None,
    provider: Provider = GENERIC,
    request_id: str | None = None,
    retry_after: float | None = None,
    transient: bool = False,
    raw: Any = None,
)

Bases: APIStatusError

HTTP 402: payment is required.

ConflictError

ConflictError(
    *,
    status: int,
    message: str | None = None,
    code: str | None = None,
    error_type: str | None = None,
    provider: Provider = GENERIC,
    request_id: str | None = None,
    retry_after: float | None = None,
    transient: bool = False,
    raw: Any = None,
)

Bases: APIStatusError

HTTP 409: the request conflicts with the resource state.

ContentTooLargeError

ContentTooLargeError(
    *,
    status: int,
    message: str | None = None,
    code: str | None = None,
    error_type: str | None = None,
    provider: Provider = GENERIC,
    request_id: str | None = None,
    retry_after: float | None = None,
    transient: bool = False,
    raw: Any = None,
)

Bases: APIStatusError

HTTP 413: the request is larger than the API accepts (RFC 9110).

GatewayTimeoutError

GatewayTimeoutError(
    *,
    status: int,
    message: str | None = None,
    code: str | None = None,
    error_type: str | None = None,
    provider: Provider = GENERIC,
    request_id: str | None = None,
    retry_after: float | None = None,
    transient: bool = False,
    raw: Any = None,
)

Bases: APIStatusError

HTTP 504: an upstream server did not respond in time.

InternalServerError

InternalServerError(
    *,
    status: int,
    message: str | None = None,
    code: str | None = None,
    error_type: str | None = None,
    provider: Provider = GENERIC,
    request_id: str | None = None,
    retry_after: float | None = None,
    transient: bool = False,
    raw: Any = None,
)

Bases: APIStatusError

HTTP 500: the API failed unexpectedly.

NotFoundError

NotFoundError(
    *,
    status: int,
    message: str | None = None,
    code: str | None = None,
    error_type: str | None = None,
    provider: Provider = GENERIC,
    request_id: str | None = None,
    retry_after: float | None = None,
    transient: bool = False,
    raw: Any = None,
)

Bases: APIStatusError

HTTP 404: the resource does not exist.

PermissionDeniedError

PermissionDeniedError(
    *,
    status: int,
    message: str | None = None,
    code: str | None = None,
    error_type: str | None = None,
    provider: Provider = GENERIC,
    request_id: str | None = None,
    retry_after: float | None = None,
    transient: bool = False,
    raw: Any = None,
)

Bases: APIStatusError

HTTP 403: the credentials lack the required permissions.

QuotaExceededError

QuotaExceededError(
    *,
    status: int,
    message: str | None = None,
    code: str | None = None,
    error_type: str | None = None,
    provider: Provider = GENERIC,
    request_id: str | None = None,
    retry_after: float | None = None,
    transient: bool = False,
    raw: Any = None,
)

Bases: APIStatusError

The account's credits or usage limits are exhausted.

Not mapped to a status code by default; providers that report quota errors with a distinct code can return it from their resolver.

RateLimitError

RateLimitError(
    *,
    status: int,
    message: str | None = None,
    code: str | None = None,
    error_type: str | None = None,
    provider: Provider = GENERIC,
    request_id: str | None = None,
    retry_after: float | None = None,
    transient: bool = False,
    raw: Any = None,
)

Bases: APIStatusError

HTTP 429: too many requests or tokens.

RequestTimeoutError

RequestTimeoutError(
    *,
    status: int,
    message: str | None = None,
    code: str | None = None,
    error_type: str | None = None,
    provider: Provider = GENERIC,
    request_id: str | None = None,
    retry_after: float | None = None,
    transient: bool = False,
    raw: Any = None,
)

Bases: APIStatusError

HTTP 408: the server timed out waiting for the request.

ServiceUnavailableError

ServiceUnavailableError(
    *,
    status: int,
    message: str | None = None,
    code: str | None = None,
    error_type: str | None = None,
    provider: Provider = GENERIC,
    request_id: str | None = None,
    retry_after: float | None = None,
    transient: bool = False,
    raw: Any = None,
)

Bases: APIStatusError

HTTP 503: the API is temporarily unavailable.

UnprocessableEntityError

UnprocessableEntityError(
    *,
    status: int,
    message: str | None = None,
    code: str | None = None,
    error_type: str | None = None,
    provider: Provider = GENERIC,
    request_id: str | None = None,
    retry_after: float | None = None,
    transient: bool = False,
    raw: Any = None,
)

Bases: APIStatusError

HTTP 422: the request is well-formed but semantically invalid.

APIConnectionError

APIConnectionError(
    message: str = "Failed to connect to the API.",
)

Bases: APITransportError

The connection could not be established or was lost.

Create a retryable connection error.

Parameters:

Name Type Description Default
message str

Description of the failure.

'Failed to connect to the API.'

APIRedirectError

APIRedirectError(
    message: str = "Redirect was not followed.",
)

Bases: APITransportError

A redirect was not followed; retrying will not help.

Raised when redirects are off (the default), lead to another origin, lack a Location header or loop.

Create a non-retryable redirect error.

Parameters:

Name Type Description Default
message str

Description of the failure.

'Redirect was not followed.'

APIRequestError

APIRequestError(
    message: str = "Failed to send the request.",
)

Bases: APITransportError

The request itself cannot be sent; retrying will not help.

Raised when an upload source fails (a missing file, a stream that raises) or the HTTP client rejects a header or the URL.

Create a non-retryable request error.

Parameters:

Name Type Description Default
message str

Description of the failure.

'Failed to send the request.'

APIStreamInterruptedError

APIStreamInterruptedError(
    message: str = "The stream was interrupted.",
    *,
    items_received: int,
)

Bases: APITransportError

An open stream broke or ended before it was complete.

Never retried: the request has already started a generation, and sending it again would start (and bill) a new one. Raised while iterating a stream when the transport fails mid-way (the original error, such as an APIConnectionError or the APITimeoutError of a silent stream, is the __cause__), and when the body ends before the method's terminal event (no __cause__).

Attributes:

Name Type Description
items_received

Items the stream had delivered before it broke.

Create a non-retryable stream error.

Parameters:

Name Type Description Default
message str

Description of the failure.

'The stream was interrupted.'
items_received int

Items the stream had delivered before it broke.

required

APITimeoutError

APITimeoutError(message: str = 'API request timed out.')

Bases: APITransportError

The request or a read from the stream exceeded its timeout.

Create a retryable timeout error.

Parameters:

Name Type Description Default
message str

Description of the failure.

'API request timed out.'

APITLSError

APITLSError(
    message: str = "TLS connection verification failed.",
)

Bases: APITransportError

TLS verification failed; retrying will not help.

Create a non-retryable TLS error.

Parameters:

Name Type Description Default
message str

Description of the failure.

'TLS connection verification failed.'

APITransportError

APITransportError(message: str, *, transient: bool = True)

Bases: AIAPIError

The request failed below the HTTP layer.

Attributes:

Name Type Description
transient

Whether retrying the request may succeed.

Store the message and the retry hint.

Parameters:

Name Type Description Default
message str

Description of the failure.

required
transient bool

Whether the request may be retried.

True