Errors¶

The full exception hierarchy. All exceptions inherit from RtlsError.

RtlsError ¶

RtlsError(message, *, status_code=None, request_url=None, request_method=None, response_body=None, error_envelope=None)

Bases: Exception

Base for every SDK exception.

Attributes:

Name	Type	Description
`status_code`		HTTP status code, or `None` for transport-level failures.
`request_url`		The URL the SDK attempted to call. Includes the path; query string may be present.
`request_method`		Uppercase HTTP method (`"GET"`, `"POST"`, …).
`response_body`		Parsed response body with secrets redacted, or `None` if the server returned no parseable body.
`error_envelope`		The server's `error` or `message` field if either was present.

AuthenticationError ¶

AuthenticationError(message, *, status_code=None, request_url=None, request_method=None, response_body=None, error_envelope=None)

Bases: RtlsError

401 after the SDK already tried to re-authenticate, or no credentials.

For from_env() and explicit-credential clients this means the username/password is invalid (or the token was revoked). For bring-your-own-token clients this means the token is invalid or expired; the caller must acquire a fresh token and reconstruct the client.

PermissionDenied ¶

PermissionDenied(message, *, status_code=None, request_url=None, request_method=None, response_body=None, error_envelope=None)

Bases: RtlsError

The authenticated user lacks permission for the requested action.

NotFound ¶

NotFound(message, *, status_code=None, request_url=None, request_method=None, response_body=None, error_envelope=None)

Bases: RtlsError

The requested resource does not exist (or is hidden by scope).

Conflict ¶

Conflict(message, *, status_code=None, request_url=None, request_method=None, response_body=None, error_envelope=None)

Bases: RtlsError

The request conflicts with current server state (e.g. duplicate MAC).

ValidationError ¶

ValidationError(message, *, field_errors=None, **kwargs)

Bases: RtlsError

The request body failed server-side validation.

field_errors is populated when the server returned a structured field-level error response. The shape varies by endpoint; consult the raised exception's response_body for the raw form.

RateLimited ¶

RateLimited(message, *, retry_after_seconds=None, **kwargs)

Bases: RtlsError

429 or 423. Server rate-limit hit.

retry_after_seconds is parsed from the Retry-After header when present. The SDK does not auto-retry; the caller decides whether to sleep and try again.

ServerError ¶

ServerError(message, *, status_code=None, request_url=None, request_method=None, response_body=None, error_envelope=None)

Bases: RtlsError

5xx. The server failed. Retry at the caller's discretion.

ConnectionError ¶

ConnectionError(message, *, status_code=None, request_url=None, request_method=None, response_body=None, error_envelope=None)

Bases: RtlsError

Transport-level failure: DNS, connection refused, read timeout, TLS.

PartialFailureError ¶

PartialFailureError(message, *, completed_steps, failed_step, cause, partial_result=None, **kwargs)

Bases: RtlsError

A compound multi-call operation failed partway through.

Raised by compound SDK methods (M4+) when an intermediate step succeeds and a subsequent step fails. The exception carries enough context for the caller to reason about the inconsistent state and decide whether to roll back further manually.

Attributes:

Name	Type	Description
`completed_steps`		Stable step-name strings for each call that succeeded before the failure. Documented per-method.
`failed_step`		Stable step-name string identifying the call that raised.
`cause`		The underlying exception that caused the failure. Also chained via `raise ... from cause`.
`partial_result`	`dict[str, Any]`	Identifiers for any partially-created resources, so the caller can clean up manually. Stable keys documented per-method.

ReportError ¶

ReportError(message, *, status_code=None, request_url=None, request_method=None, response_body=None, error_envelope=None)

Bases: RtlsError

Base for report-specific failures.

ReportFailed ¶

ReportFailed(message, *, status_code=None, request_url=None, request_method=None, response_body=None, error_envelope=None)

Bases: ReportError

The server reported an error in the report's status payload.

ReportTimeout ¶

ReportTimeout(message, *, report_uid=None, **kwargs)

Bases: ReportError

The SDK's polling deadline elapsed before the report completed.

report_uid carries the in-flight report's identifier so the caller can resume polling later by calling reports.get(report_uid).

WsError ¶

WsError(message, *, status_code=None, request_url=None, request_method=None, response_body=None, error_envelope=None)

Bases: RtlsError

Base class for WebSocket surface errors.

Raised from :class:WsAPI and the iterator returned by :meth:WsAPI.subscribe. Subclasses pin specific failure modes; catch WsError to handle any WS-side failure uniformly. Future streaming protocols (MQTT, Kafka) would carry their own error hierarchies; this base intentionally does not generalize beyond WS.

WsAuthError ¶

WsAuthError(message, *, status_code=None, request_url=None, request_method=None, response_body=None, error_envelope=None)

Bases: WsError

The WS server rejected the credentials on subscribe.

Surfaced from the session iterator the first time the server's response (or close behavior) indicates the token / email pair was not accepted on add. Reconnection stops on auth failure.

WsProtocolError ¶

WsProtocolError(message, *, status_code=None, request_url=None, request_method=None, response_body=None, error_envelope=None)

Bases: WsError

The WS server returned a malformed or unexpected JSON-RPC frame.

Reserved for fatal frame-shape violations. The session's reader tolerates an isolated bad frame (logged + skipped); a WsProtocolError indicates something the session cannot recover from.

LsbConvergenceError ¶

LsbConvergenceError(message, *, unresolved, **kwargs)

Bases: RtlsError

client.lsb.start() / stop() didn't converge within the timeout.

unresolved lists the MACs that did not reach the target state before the timeout elapsed. Inspect to decide whether to retry, take individual nodes offline, or accept the partial state.