A failed DCP call or API request raises a halyard.HalyardError subclass, importable from halyard. Branch on the class or on kind, never on the message text. A few failures raise other exceptions; see Not a HalyardError.
from halyard import HalyardError, TimeoutError

try:
    page.get_by_role("button", name="Checkout").click(timeout=3000)
except TimeoutError as e:
    print(e.kind, e.method)        # ActionTimeout Locator.click
except HalyardError as e:
    if e.retryable:
        ...

HalyardError

AttributeTypeDescription
kindstrThe DCP error kind, such as ActionTimeout.
methodstrThe DCP method that failed, such as Locator.click.
codeint | NoneThe DCP error code, or the HTTP status for a session client error.
retryableboolWhether sending the same call again can succeed.

Subclasses

ClassDCP kindsRaised when
TimeoutErrorActionTimeout, TimeoutAn element never became actionable, a wait ran out, a locator matched several elements, or no reply came within the client’s wait (kind Timeout). Same name as Playwright’s.
EvaluationErrornoneA script passed to evaluate threw. stack holds its stack trace.
InvalidArgsErrorInvalidArgsThe arguments were rejected: a malformed selector, an unknown key, a refused chord, a script result over 1 MiB. Also HTTP 400 and 422.
UnsupportedErrorStrategyUnavailable, UnknownOpThe session doesn’t serve this method, option or strategy.
NavigationErrorNavigationFailedChrome couldn’t load the page.
TargetNotFoundErrorTargetNotFoundThe tab doesn’t exist, or was closed.
NotConnectedErrorNotConnected, DeviceOffline, NoAllocationThe control socket couldn’t open (including a refused token or an ended session), closed while a call waited for its reply, or was already closed.
UnauthorizedErrorUnauthorizedThe token or API key was refused. Also HTTP 401 and 403.
ConflictErrorConflictThe request conflicts with the session’s state. Also HTTP 409.
DialogOpenErrorDialogOpenA dialog held open by a page.on("dialog") listener blocks the page, and no listener answered it.
StaleNodeErrorStaleNodeA node reference from an earlier read is gone: a phone’s node_id, or a browser [ref=...] from aria_snapshot(refs=True).
TreeUnavailableErrorTreeUnavailableThe accessibility tree has nothing to read right now. Phones only.

Phone-specific

These come up only on a phone:
ErrorWhen
StaleNodeErrorA locator pinned with node_id, or accessibility.partial() or children(), names a node that has left the screen. Take a fresh accessibility.snapshot().
TreeUnavailableErrorThe accessibility tree is on but has no app window to read, such as while a system dialog is up.
UnsupportedError for a strategyA locator needs the accessibility tree (role, name, states, node_id, strategy="accessibility", wait_for(state="enabled"), accessible_name()) and the phone has none; or a selector kind or strategy the phone doesn’t serve, such as dom. halyard.phone.StrategyUnavailableError is another name for it.
InvalidArgsError for a removed fieldphone.locator() given id, value, window_id, android_class_name or package_name, or phone.get_by_id().
ValueErrorA phone locator timeout outside 0 to 60,000 milliseconds, or a within() or has() locator that sets its own strategy, model or OCR engine.
halyard.phone.ActionTimeoutError is another name for TimeoutError.

Computer-specific

ErrorWhen
TargetNotFoundErrorA file or folder doesn’t exist (files.read_text(), stat()).
InvalidArgsErrorA write under C:\ax other than C:\ax\downloads; a file over 32 MiB; reading a folder; ending a protected process; a resolution that isn’t a display mode.
TimeoutErrorwindows.wait_for() ran out. A processes.run() that runs out does not raise: its result has timed_out set.

Browser-specific

ErrorWhen
DialogOpenErrorA page.on("dialog") listener returned without calling accept() or dismiss(), so the dialog still blocks the page.
InvalidArgsErrorframe_locator() given a selector that isn’t CSS, or an element that isn’t an <iframe>; answering a dialog twice.
NavigationErrordownload.save_as() or path() on a failed download.

Other kinds

Any other DCP kind raises HalyardError itself. So does any other HTTP error status from the session client. A reply that doesn’t arrive within the connection’s timeout (the timeout= given to connect(), 60 seconds by default) raises TimeoutError with kind Timeout. Calls given a longer timeout of their own wait that long, plus a margin. from halyard import TimeoutError shadows Python’s built-in TimeoutError, as Playwright’s does.

Not a HalyardError

These come from Python or the libraries underneath, so catch them separately where they matter:
ExceptionWhen
httpx.HTTPError (such as httpx.ConnectError, httpx.TimeoutException)The session client (Client) can’t reach the API or times out. An HTTP error status is a HalyardError.
websockets.exceptions.ConnectionClosedA browser or computer control socket closed and a new call is sent on it. A call already waiting for its reply raises NotConnectedError instead.
ValueErrorAn argument checked before anything is sent: no API key or control URL, a screenshot type other than "png" or "jpeg", an upload payload without name or buffer.
TypeErrorset_input_files() given something that isn’t a path or a payload.
OSErrorA local file can’t be read or written (set_input_files(), save_as(), files.upload(), screenshot(path=...)).
AssertionErrorAn expect() assertion still fails when its timeout runs out.