Exceptions

Catch brimp.BrimpError for Brimp failures, or brimp.RequestException for HTTP request failures. Every exception below is available from both brimp and brimp.exceptions. brimp.RequestsError is another spelling of brimp.RequestException. There is no CurlError base or public low-level Curl object.

Request exceptions expose .code, the numeric curl error code, or 0 when the failure comes from Brimp's validation, redirect policy or operation deadline. Classification also uses native CONNECT and TLS verification results. For example, a certificate failure can raise CertificateVerifyError while .code retains a generic connection code returned after HTTP/3 fallback.

They also expose .response and .page. Both refer to the Page/AsyncPage for raise_for_status() and json() failures. Native transfer failures currently leave these fields as None, including failures after partial response data has arrived; a previous response on a reused page is never attached to that failure.

import brimp

try:
    with brimp.get("https://example.com/") as page:
        page.raise_for_status()
except brimp.CertificateVerifyError as error:
    print("Certificate verification failed", error.code)
except brimp.RequestException as error:
    print("Request failed", error.code)

HTTP status codes alone do not raise. Call page.raise_for_status() to raise brimp.HTTPError for a 4xx/5xx response. Its .status_code and .url retain the failed response's values even if the attached live page navigates again. HTTPError also represents curl HTTP protocol failures, for which these fields are None when there is no response object.

RequestTimeout inherits both TransportError and Timeout. A deadline reached while fetching the navigation response or reading a stream raises RequestTimeout. A deadline reached while executing page JavaScript or waiting for browser operations raises Timeout, which is not a RequestException. Connect and read phases are not yet exposed as separate exception types.

Runtime errors such as JavaScriptError, Reentry and StaleHandle remain separate from HTTP failures. Request exceptions also inherit RuntimeError and OSError. URL/header validation errors inherit InvalidInput and ValueError; SessionClosed inherits Closed. Async operations use the same exception types, and task cancellation still raises asyncio.CancelledError.

JSONDecodeError also inherits the standard library's json.JSONDecodeError, retains its decoder position fields, and chains the original decoding error.

Common bases and runtime errors

brimp.BrimpError

Base class for Brimp failures.

brimp.RuntimeError

A browser-runtime or host operation failed.

brimp.RequestException

RequestException(message, code=0, response=None)

Base for HTTP request failures; response is a Page/AsyncPage or None.

Source code in brimp/exceptions.py
45
46
47
48
49
def __init__(self, message, code=0, response=None):
    super().__init__(message)
    self.code = int(code)
    self.response = response
    self.page = response

code instance-attribute

code = int(code)

page instance-attribute

page = response

response instance-attribute

response = response

brimp.TransportError

TransportError(message, code=0, response=None)

A network transfer failed.

Source code in brimp/exceptions.py
45
46
47
48
49
def __init__(self, message, code=0, response=None):
    super().__init__(message)
    self.code = int(code)
    self.response = response
    self.page = response

code instance-attribute

code = int(code)

page instance-attribute

page = response

response instance-attribute

response = response

brimp.InvalidInput

Invalid arguments or unsupported input configuration.

brimp.JavaScriptError

Page JavaScript evaluation failed.

brimp.Timeout

A runtime operation or HTTP request exceeded its deadline.

brimp.Closed

The page, session or handle has been closed.

brimp.Reentry

A host callback attempted to reenter its page or session.

brimp.StaleHandle

A handle belongs to an expired realm or was disposed.

HTTP and transport errors

brimp.ConnectionError

ConnectionError(message, code=0, response=None)

Connection establishment or communication failed.

Source code in brimp/exceptions.py
45
46
47
48
49
def __init__(self, message, code=0, response=None):
    super().__init__(message)
    self.code = int(code)
    self.response = response
    self.page = response

code instance-attribute

code = int(code)

page instance-attribute

page = response

response instance-attribute

response = response

brimp.DNSError

DNSError(message, code=0, response=None)

The destination hostname could not be resolved.

Source code in brimp/exceptions.py
45
46
47
48
49
def __init__(self, message, code=0, response=None):
    super().__init__(message)
    self.code = int(code)
    self.response = response
    self.page = response

code instance-attribute

code = int(code)

page instance-attribute

page = response

response instance-attribute

response = response

brimp.ProxyError

ProxyError(message, code=0, response=None)

Proxy resolution, negotiation or tunneling failed.

Source code in brimp/exceptions.py
45
46
47
48
49
def __init__(self, message, code=0, response=None):
    super().__init__(message)
    self.code = int(code)
    self.response = response
    self.page = response

code instance-attribute

code = int(code)

page instance-attribute

page = response

response instance-attribute

response = response

brimp.SSLError

SSLError(message, code=0, response=None)

TLS negotiation or configuration failed.

Source code in brimp/exceptions.py
45
46
47
48
49
def __init__(self, message, code=0, response=None):
    super().__init__(message)
    self.code = int(code)
    self.response = response
    self.page = response

code instance-attribute

code = int(code)

page instance-attribute

page = response

response instance-attribute

response = response

brimp.CertificateVerifyError

CertificateVerifyError(message, code=0, response=None)

The peer certificate could not be verified.

Source code in brimp/exceptions.py
45
46
47
48
49
def __init__(self, message, code=0, response=None):
    super().__init__(message)
    self.code = int(code)
    self.response = response
    self.page = response

code instance-attribute

code = int(code)

page instance-attribute

page = response

response instance-attribute

response = response

brimp.RequestTimeout

RequestTimeout(message, code=0, response=None)

An HTTP transfer exceeded its deadline, unlike a JavaScript timeout.

Source code in brimp/exceptions.py
45
46
47
48
49
def __init__(self, message, code=0, response=None):
    super().__init__(message)
    self.code = int(code)
    self.response = response
    self.page = response

code instance-attribute

code = int(code)

page instance-attribute

page = response

response instance-attribute

response = response

brimp.HTTPError

HTTPError(message, code=0, response=None)

HTTP status or protocol failure; status_code and url snapshot the response.

Source code in brimp/exceptions.py
87
88
89
90
def __init__(self, message, code=0, response=None):
    super().__init__(message, code, response)
    self.status_code = None if response is None else response.status_code
    self.url = None if response is None else response.url

code instance-attribute

code = int(code)

page instance-attribute

page = response

response instance-attribute

response = response

status_code instance-attribute

status_code = None if response is None else response.status_code

url instance-attribute

url = None if response is None else response.url

brimp.IncompleteRead

IncompleteRead(message, code=0, response=None)

The response ended before all declared bytes arrived.

Source code in brimp/exceptions.py
87
88
89
90
def __init__(self, message, code=0, response=None):
    super().__init__(message, code, response)
    self.status_code = None if response is None else response.status_code
    self.url = None if response is None else response.url

code instance-attribute

code = int(code)

page instance-attribute

page = response

response instance-attribute

response = response

status_code instance-attribute

status_code = None if response is None else response.status_code

url instance-attribute

url = None if response is None else response.url

brimp.TooManyRedirects

TooManyRedirects(message, code=0, response=None)

The redirect limit was exceeded.

Source code in brimp/exceptions.py
45
46
47
48
49
def __init__(self, message, code=0, response=None):
    super().__init__(message)
    self.code = int(code)
    self.response = response
    self.page = response

code instance-attribute

code = int(code)

page instance-attribute

page = response

response instance-attribute

response = response

brimp.SessionClosed

SessionClosed(message, code=0, response=None)

An operation used a closed session.

Source code in brimp/exceptions.py
45
46
47
48
49
def __init__(self, message, code=0, response=None):
    super().__init__(message)
    self.code = int(code)
    self.response = response
    self.page = response

code instance-attribute

code = int(code)

page instance-attribute

page = response

response instance-attribute

response = response

brimp.ImpersonateError

ImpersonateError(message, code=0, response=None)

The transport impersonation profile could not be applied.

Source code in brimp/exceptions.py
45
46
47
48
49
def __init__(self, message, code=0, response=None):
    super().__init__(message)
    self.code = int(code)
    self.response = response
    self.page = response

code instance-attribute

code = int(code)

page instance-attribute

page = response

response instance-attribute

response = response

brimp.InterfaceError

InterfaceError(message, code=0, response=None)

The configured outgoing interface could not be used.

Source code in brimp/exceptions.py
45
46
47
48
49
def __init__(self, message, code=0, response=None):
    super().__init__(message)
    self.code = int(code)
    self.response = response
    self.page = response

code instance-attribute

code = int(code)

page instance-attribute

page = response

response instance-attribute

response = response

Validation and decoding errors

brimp.InvalidURL

InvalidURL(message, code=0, response=None)

The request URL is malformed.

Source code in brimp/exceptions.py
45
46
47
48
49
def __init__(self, message, code=0, response=None):
    super().__init__(message)
    self.code = int(code)
    self.response = response
    self.page = response

code instance-attribute

code = int(code)

page instance-attribute

page = response

response instance-attribute

response = response

brimp.MissingSchema

MissingSchema(message, code=0, response=None)

The request URL has no scheme and no base URL resolves it.

Source code in brimp/exceptions.py
45
46
47
48
49
def __init__(self, message, code=0, response=None):
    super().__init__(message)
    self.code = int(code)
    self.response = response
    self.page = response

code instance-attribute

code = int(code)

page instance-attribute

page = response

response instance-attribute

response = response

brimp.InvalidSchema

InvalidSchema(message, code=0, response=None)

The request URL uses an unsupported scheme.

Source code in brimp/exceptions.py
45
46
47
48
49
def __init__(self, message, code=0, response=None):
    super().__init__(message)
    self.code = int(code)
    self.response = response
    self.page = response

code instance-attribute

code = int(code)

page instance-attribute

page = response

response instance-attribute

response = response

brimp.InvalidProxyURL

InvalidProxyURL(message, code=0, response=None)

The proxy URL is malformed or unsupported.

Source code in brimp/exceptions.py
45
46
47
48
49
def __init__(self, message, code=0, response=None):
    super().__init__(message)
    self.code = int(code)
    self.response = response
    self.page = response

code instance-attribute

code = int(code)

page instance-attribute

page = response

response instance-attribute

response = response

brimp.InvalidHeader

InvalidHeader(message, code=0, response=None)

A request header name or value is invalid.

Source code in brimp/exceptions.py
45
46
47
48
49
def __init__(self, message, code=0, response=None):
    super().__init__(message)
    self.code = int(code)
    self.response = response
    self.page = response

code instance-attribute

code = int(code)

page instance-attribute

page = response

response instance-attribute

response = response

brimp.InvalidJSONError

InvalidJSONError(message, code=0, response=None)

The response body could not be decoded as JSON.

Source code in brimp/exceptions.py
45
46
47
48
49
def __init__(self, message, code=0, response=None):
    super().__init__(message)
    self.code = int(code)
    self.response = response
    self.page = response

code instance-attribute

code = int(code)

page instance-attribute

page = response

response instance-attribute

response = response

brimp.JSONDecodeError

JSONDecodeError(message, doc, pos, *, response=None)

JSON failure retaining the stdlib decoder's msg, doc and pos fields.

Source code in brimp/exceptions.py
140
141
142
def __init__(self, message, doc, pos, *, response=None):
    _json.JSONDecodeError.__init__(self, message, doc, pos)
    RequestException.__init__(self, self.args[0], response=response)

code instance-attribute

code = int(code)

page instance-attribute

page = response

response instance-attribute

response = response