Skip to content

Exceptions

This page lists exceptions that may be raised when using HTTPX.

For an overview of how to work with HTTPX exceptions, see Exceptions (Quickstart).

The exception hierarchy

  • HTTPError
    • RequestError
      • TransportError
        • TimeoutException
          • ConnectTimeout
          • ReadTimeout
          • WriteTimeout
          • PoolTimeout
        • NetworkError
          • ConnectError
          • ReadError
          • WriteError
          • CloseError
        • ProtocolError
          • LocalProtocolError
          • RemoteProtocolError
        • ProxyError
        • UnsupportedProtocol
      • DecodingError
      • TooManyRedirects
    • HTTPStatusError
  • InvalidURL
  • CookieConflict
  • StreamError
    • StreamConsumed
    • ResponseNotRead
    • RequestNotRead
    • StreamClosed

Exception classes

httpx2.HTTPError

Bases: Exception

Base class for RequestError and HTTPStatusError.

Useful for try...except blocks when issuing a request, and then calling .raise_for_status().

For example:

try:
    response = httpx2.get("https://www.example.com")
    response.raise_for_status()
except httpx2.HTTPError as exc:
    print(f"HTTP Exception for {exc.request.url} - {exc}")

httpx2.RequestError

Bases: HTTPError

Base class for all exceptions that may occur when issuing a .request().

httpx2.TransportError

Bases: RequestError

Base class for all exceptions that occur at the level of the Transport API.

httpx2.TimeoutException

Bases: TransportError

The base class for timeout errors.

An operation has timed out.

httpx2.ConnectTimeout

Bases: TimeoutException

Timed out while connecting to the host.

httpx2.ReadTimeout

Bases: TimeoutException

Timed out while receiving data from the host.

httpx2.WriteTimeout

Bases: TimeoutException

Timed out while sending data to the host.

httpx2.PoolTimeout

Bases: TimeoutException

Timed out waiting to acquire a connection from the pool.

httpx2.NetworkError

Bases: TransportError

The base class for network-related errors.

An error occurred while interacting with the network.

httpx2.ConnectError

Bases: NetworkError

Failed to establish a connection.

httpx2.ReadError

Bases: NetworkError

Failed to receive data from the network.

httpx2.WriteError

Bases: NetworkError

Failed to send data through the network.

httpx2.CloseError

Bases: NetworkError

Failed to close a connection.

httpx2.ProtocolError

Bases: TransportError

The protocol was violated.

httpx2.LocalProtocolError

Bases: ProtocolError

A protocol was violated by the client.

For example if the user instantiated a Request instance explicitly, failed to include the mandatory Host: header, and then issued it directly using client.send().

httpx2.RemoteProtocolError

Bases: ProtocolError

The protocol was violated by the server.

For example, returning malformed HTTP.

httpx2.ProxyError

Bases: TransportError

An error occurred while establishing a proxy connection.

httpx2.UnsupportedProtocol

Bases: TransportError

Attempted to make a request to an unsupported protocol.

For example issuing a request to ftp://www.example.com.

httpx2.DecodingError

Bases: RequestError

Decoding of the response failed, due to a malformed encoding.

httpx2.TooManyRedirects

Bases: RequestError

Too many redirects.

httpx2.HTTPStatusError

Bases: HTTPError

The response had an error HTTP status of 4xx or 5xx.

May be raised when calling response.raise_for_status()

httpx2.InvalidURL

Bases: Exception

URL is improperly formed or cannot be parsed.

httpx2.CookieConflict

Bases: Exception

Attempted to lookup a cookie by name, but multiple cookies existed.

Can occur when calling response.cookies.get(...).

httpx2.StreamError

Bases: RuntimeError

The base class for stream exceptions.

The developer made an error in accessing the request stream in an invalid way.

httpx2.StreamConsumed

Bases: StreamError

Attempted to read or stream content, but the content has already been streamed.

httpx2.StreamClosed

Bases: StreamError

Attempted to read or stream response content, but the request has been closed.

httpx2.ResponseNotRead

Bases: StreamError

Attempted to access streaming response content, without having called read().

httpx2.RequestNotRead

Bases: StreamError

Attempted to access streaming request content, without having called read().