Skip to content

xtr_http_client_contracts.exception

The errors the HTTP client contract names.

:class:HttpClientError is the root every one of them derives from, including every error an implementation adds, so catching it catches anything calling out can go wrong with, whichever client raised it.

Below it, two branches that mean different things. A :class:TransportError — with :class:TransportTimeoutError for running out of time — says there is no answer to look at. An :class:HttpError says there is one and it is not a success: :class:RedirectionError for a 3xx nobody followed, :class:ClientError for a 4xx, :class:ServerError for a 5xx, each carrying the response. :class:DecodingError is the third case: the answer arrived whole and is not what it was being read as.

ClientError

ClientError(response: HttpResponseInterface, reason: str)

Bases: HttpError

A 4xx status: the server understood the request and would not serve it.

Retrying the same request unchanged gets the same answer, so this is the one range worth telling apart — a 401 asks for credentials, a 404 says there is nothing there, a 429 says to slow down.

DecodingError

DecodingError(reason: str)

Bases: HttpClientError, ValueError

A body could not be turned into the shape that was asked for.

What :meth:HttpResponseInterface.to_array <xtr_http_client_contracts.http_response_interface.HttpResponseInterface.to_array> raises when the body is empty, is not JSON, or is JSON that is not an object. The transfer succeeded, so this is about the payload, not the connection.

Also a :class:ValueError, so code that already guards what it parses with except ValueError keeps working without learning a new exception.

Attributes:

  • reason (str) –

    What is wrong with the body, naming the URL it came from.

Record what is wrong with the body.

HttpClientError

Bases: Exception

Base class for every error raised through the HTTP client contract.

Catch this to handle anything calling out can go wrong with, whichever client is behind the interface; catch a subclass to handle one cause. Every subclass carries what a caller needs as typed attributes and composes its message from them.

A server answering is not a cause: a request that came back with a 404 or a 503 succeeded as a transfer, so request() returns the response and nothing is raised until someone reads its content and asks to be told. What raises on its own is the transfer failing, a body that will not decode, and an option no client here understands.

HttpError

HttpError(response: HttpResponseInterface, reason: str)

Bases: HttpClientError

The status code says the request did not get what it asked for.

Never raised by making the request: a status is an answer, not a failure of the transfer, so it reaches the caller as a response. This is raised where the caller asks to be told about it — :meth:HttpResponseInterface.get_content <xtr_http_client_contracts.http_response_interface.HttpResponseInterface.get_content> or :meth:HttpResponseInterface.to_array <xtr_http_client_contracts.http_response_interface.HttpResponseInterface.to_array> with throw.

Catch this to handle any unsuccessful status; :class:RedirectionError <...redirection_error.RedirectionError>, :class:ClientError <...client_error.ClientError> and :class:ServerError <...server_error.ServerError> are the three ranges, and they are siblings, so catching one leaves the others alone.

The response comes along because it is the only place the answer is left: the status code, the headers and the body, which is kept.

Attributes:

  • response (HttpResponseInterface) –

    The response that was answered with.

  • reason (str) –

    What the status means for this request, naming the code and the URL. The message is this, composed by whoever raised it — the body of an error document is the most useful thing to put there and reading it is awaited, which a constructor cannot do.

Record the response the status came on, and what it means.

InvalidArgumentError

InvalidArgumentError(reason: str)

Bases: TransportError, ValueError

The request was refused before it was sent, for something it asked for.

An unknown option name, an option whose value the client cannot honour, a method or URL it cannot make a request with, or a body given both with the request and as an option. Nothing reached the network, so there is no response, and the same call with a corrected argument would go through.

Also a :class:ValueError, so code that already guards the arguments it passes with except ValueError keeps working without learning a new exception.

JsonError

JsonError(reason: str)

Bases: DecodingError

The body is JSON, but not the object :meth:HttpResponseInterface.to_array promises.

A JSON array, string, number or null where an object was asked for. The body was read in full and parsed, so the failure is the shape of the payload, not the transfer.

Also a :class:DecodingError, so code that already catches a body it could not decode keeps catching this one.

RedirectionError

RedirectionError(response: HttpResponseInterface, reason: str)

Bases: HttpError

A 3xx status that was not followed.

Raised once max_redirects has been reached, or straight away when following was turned off with max_redirects of zero or less — a redirect that is followed never reaches the caller, since what comes back is the response from the last hop.

Where the answer points is in the redirect_url entry of :meth:HttpResponseInterface.get_info <xtr_http_client_contracts.http_response_interface.HttpResponseInterface.get_info>.

ServerError

ServerError(response: HttpResponseInterface, reason: str)

Bases: HttpError

A 5xx status: the request may have been fine, the server was not.

The far side is at fault, so the same request may well succeed later. Nothing here retries; what to do about it is the caller's to decide.

TransportError

TransportError(reason: str)

Bases: HttpClientError

Nothing usable came back, or the request could never be made.

A host that will not resolve, a connection refused or reset, a body that stopped half way, a certificate the client would not accept — and the one case that never touches the network: an option the client does not support. A client reports that by raising rather than by ignoring it, so an option that was spelled wrong, or that this client cannot honour, cannot pass for one it quietly obeyed.

It is also what reading a response raises once it has been cancelled.

Attributes:

  • reason (str) –

    What went wrong, naming the URL it went wrong for.

Record what went wrong.

TransportTimeoutError

TransportTimeoutError(reason: str)

Bases: TransportError, TimeoutError

The transfer went quiet for longer than it was allowed to.

Raised when the idle timeout passes with nothing coming in, when the whole transfer outlasts max_duration, or when connecting outlasts max_connect_duration.

Also a :class:TimeoutError, which is what the standard library raises and what asyncio.timeout turns a deadline into, so code that already gives up on a timeout keeps working without learning a new exception.