Skip to content

Exceptions

exceptions

Exception hierarchy for the Home Assistant client.

All library-specific exceptions derive from HAClientError so callers can catch a single base type if they do not care about the specific failure.

HAClientError

Bases: Exception

Base class for all exceptions raised by haclient.

Source code in src/haclient/exceptions.py 
10
11
class HAClientError(Exception):
    """Base class for all exceptions raised by ``haclient``."""

AuthenticationError

Bases: HAClientError

Raised when authentication with Home Assistant fails.

Source code in src/haclient/exceptions.py 
14
15
class AuthenticationError(HAClientError):
    """Raised when authentication with Home Assistant fails."""

ConnectionClosedError

Bases: HAClientError

Raised when the WebSocket connection is unexpectedly closed.

Source code in src/haclient/exceptions.py 
18
19
class ConnectionClosedError(HAClientError):
    """Raised when the WebSocket connection is unexpectedly closed."""

CommandError

Bases: HAClientError

Raised when Home Assistant returns an error for a WebSocket command.

Attributes:

Name Type Description
code str

The error code from Home Assistant.
message str

The human-readable error message.
Source code in src/haclient/exceptions.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
class CommandError(HAClientError):
    """Raised when Home Assistant returns an error for a WebSocket command.

    Attributes
    ----------
    code : str
        The error code from Home Assistant.
    message : str
        The human-readable error message.
    """

    def __init__(self, code: str, message: str) -> None:
        super().__init__(f"{code}: {message}")
        self.code = code
        self.message = message

HTTPError

Bases: HAClientError

Raised when Home Assistant returns an HTTP error response.

Parameters:

Name Type Description Default
status int

The HTTP status code (e.g. 404, 500).

 required
method str

The HTTP method used (e.g. "GET").

 required
path str

The relative API path that was requested.

 required
body str

The response body text.

 required

Attributes:

Name Type Description
status int

The HTTP status code.
method str

The HTTP method.
path str

The relative API path.
body str

The response body text.

Examples:

>>> raise HTTPError(404, "GET", "/api/states/light.missing", "not found")
Source code in src/haclient/exceptions.py 
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
class HTTPError(HAClientError):
    """Raised when Home Assistant returns an HTTP error response.

    Parameters
    ----------
    status : int
        The HTTP status code (e.g. 404, 500).
    method : str
        The HTTP method used (e.g. ``"GET"``).
    path : str
        The relative API path that was requested.
    body : str
        The response body text.

    Attributes
    ----------
    status : int
        The HTTP status code.
    method : str
        The HTTP method.
    path : str
        The relative API path.
    body : str
        The response body text.

    Examples
    --------
    >>> raise HTTPError(404, "GET", "/api/states/light.missing", "not found")
    """

    def __init__(self, status: int, method: str, path: str, body: str) -> None:
        super().__init__(f"HTTP {status} from {method} {path}: {body.strip()}")
        self.status = status
        self.method = method
        self.path = path
        self.body = body

TimeoutError

Bases: HAClientError

Raised when a request to Home Assistant does not complete in time.

Source code in src/haclient/exceptions.py 
77
78
class TimeoutError(HAClientError):  # noqa: A001
    """Raised when a request to Home Assistant does not complete in time."""

EntityNotFoundError

Bases: HAClientError

Raised when a requested entity cannot be resolved.

Source code in src/haclient/exceptions.py 
81
82
class EntityNotFoundError(HAClientError):
    """Raised when a requested entity cannot be resolved."""