aiollm.http¶
http
¶
Transport-neutral HTTP primitives: API, auth, headers and errors.
Modules:
| Name | Description |
|---|---|
api |
Default |
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 |
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 |
BearerAuth |
Sends the token as |
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.
BaseAPI
¶
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. |
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. |
required |
version
|
str
|
API version segment, e.g. |
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Methods:
| Name | Description |
|---|---|
build_url |
Build the absolute URL for a request. |
build_url
¶
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
¶
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 |
header_name |
str
|
Name of the header that carries the key. |
Methods:
| Name | Description |
|---|---|
encode |
Return the header value. |
BearerAuth
dataclass
¶
BearerAuth(token: str)
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 |
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
¶
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
|
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. |
version |
str
|
API version segment, e.g. |
Methods:
| Name | Description |
|---|---|
build_url |
Build the absolute URL for a request. |
build_url
¶
Build the absolute URL for a request.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
method
|
str
|
Request path of the method, e.g. |
required |
query
|
Query | None
|
Query parameters to append, already converted to
strings, not encoded yet; a list value becomes a repeated
key ( |
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 |
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 |
Attributes:
| Name | Type | Description |
|---|---|---|
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
¶
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
|
Returns:
| Type | Description |
|---|---|
HeadersDict
|
A new case-insensitive mapping. |
exceptions
¶
HTTP and transport errors and the error resolver.
Modules:
| Name | Description |
|---|---|
aiohttp |
Translation of |
protocols |
Interface for turning HTTP error responses into exceptions. |
resolver |
Default mapping of HTTP error responses to |
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 |
BaseErrorResolver |
Turns an HTTP error response into an |
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
¶
HTTP_ERRORS: Final[dict[int, type[APIStatusError]]] = {
400: BadRequestError,
401: AuthenticationError,
402: BillingError,
403: PermissionDeniedError,
404: NotFoundError,
408: RequestTimeoutError,
409: ConflictError,
413: ContentTooLargeError,
422: UnprocessableEntityError,
429: RateLimitError,
500: InternalServerError,
502: BadGatewayError,
503: ServiceUnavailableError,
504: GatewayTimeoutError,
}
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
¶
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 |
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 |
classify |
Choose the error class and whether the error is transient. |
classify_status |
Choose the error class and transience of an HTTP status. |
resolve
¶
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 |
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
¶
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 |
required |
Returns:
| Type | Description |
|---|---|
type[APIStatusError]
|
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 |
required |
Returns:
| Type | Description |
|---|---|
type[APIStatusError]
|
The |
bool
|
transient flag. |
APIResponseError
¶
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
|
|
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
|
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
¶
BadGatewayError
¶
BadRequestError
¶
BillingError
¶
ConflictError
¶
ContentTooLargeError
¶
GatewayTimeoutError
¶
InternalServerError
¶
NotFoundError
¶
PermissionDeniedError
¶
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
¶
RequestTimeoutError
¶
ServiceUnavailableError
¶
UnprocessableEntityError
¶
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
¶
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
¶
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
|