Exceptions¶
Every failure is surfaced as a BusyBarError subclass, so callers can catch
the domain error rather than transport-specific exceptions.
Bases: Exception
Base class for all BUSY Bar library exceptions.
Allows callers to handle library failures via a single except clause.
BusyBarAPIError(error: str, code: int | None = None, *, status_code: int | None = None, method: str | None = None, path: str | None = None, payload: Any | None = None, request_id: str | None = None, response_excerpt: str | None = None)
Bases: BusyBarError
Raised when the BUSY Bar API returns an error response.
Provides access to the response payload for diagnostics.
BusyBarRequestError(message: str, *, method: str | None = None, path: str | None = None, request_id: str | None = None, attempts: int | None = None, original: Exception | None = None)
Bases: BusyBarError
Raised when a request cannot be sent (network/timeout).
Used for transport-level failures before a response is received.
BusyBarAPIVersionError(*, library_version: str, device_version: str, message: str)
Bases: BusyBarError
Raised when Busy Lib and device API versions are incompatible.
Indicates that either firmware or library must be updated.
BusyBarUsbError(message: str)
Bases: BusyBarError
Raised when USB device is not connected or USB operation fails.
Covers discovery, connection, and command execution issues.
BusyBarProtocolError(message: str, *, method: str, path: str, request_id: str | None = None, response_excerpt: str | None = None)
Bases: BusyBarError
Raised when a successful HTTP response has an unexpected payload format.
Used for 2xx responses that cannot be interpreted as required by endpoint.
BusyBarResponseValidationError(*, model: str, details: str, original: Exception | None = None)
Bases: BusyBarError
Raised when a successful API response does not match expected schema.
Wraps pydantic validation errors to keep a stable domain error contract.
BusyBarConversionError(message: str, *, path: str, original: Exception | None = None)
Bases: BusyBarError
Raised when local file conversion fails before upload to the device.
Used by storage upload flows to report unsupported formats and failed conversion pipelines with a stable domain exception type.
BusyBarRemovedEndpointError(*, path: str, method: str, replacement: str | None = None)
Bases: BusyBarError
Raised when a helper targets a device endpoint that no longer exists.
Distinct from BusyBarAPIVersionError: updating the firmware will not
make the call work, because the endpoint was withdrawn rather than
added later.
BusyBarWebSocketError(message: str, *, path: str, original: Exception | None = None)
Bases: BusyBarError
Raised when WebSocket connection or stream processing fails.
Wraps low-level websocket library exceptions into a domain error type.
is_retryable_delivery_error(error: BusyBarError) -> bool
Classify BUSY Bar delivery failures for caller retry decisions.
Treats request/transport failures and explicitly transient HTTP statuses as retryable. Other 4xx responses are caller or authorization problems and should not be retried as-is.
format_delivery_error(error: BusyBarError) -> str
Format BUSY Bar delivery failure into a compact diagnostic string.
Keeps enough HTTP context and response body excerpt for service logs without duplicating full response-formatting logic in each integration.