Errors (astra.errors)

Overview

Centralized exception types used across the Astra codebase. All exceptions inherit from astra.errors.base.AstraError and include code and hint to make diagnostics actionable.

Astra Errors: Structured, coded exceptions for every failure path.

Usage:

from astra.errors import MessageSendError, ErrorCode

try:
 await client.chat.send_message(jid, text)
except MessageSendError as e:
 print(e.code)  # "E3001"
 print(e.hint)  # "Ensure the recipient JID is correct..."
 print(e.retryable) # True

exception AstraError(message, code='E0000', hint=None, severity=Severity.ERROR, retryable=False, payload=None, cause=None)

The base class for all errors in the Astra framework.

AstraError provides a structured way to report failures, including human-readable messages, unique error codes, recovery hints, severity levels, and retry guidance.

Example:

try:
 await client.chat.send_message(jid, text)
except MessageSendError as e:
 print(e.code)  # "E3001"
 print(e.hint)  # "Ensure the recipient JID is correct..."
 print(e.retryable) # True
 print(e.severity) # Severity.ERROR

Parameters:

• message (str)

• code (str)

• hint (str | None)

• severity (Severity)

• retryable (bool)

• payload (Dict[str, Any] | None)

• cause (Exception | None)

__init__(message, code='E0000', hint=None, severity=Severity.ERROR, retryable=False, payload=None, cause=None)

Initialize the error.

Parameters:

• message (str) – A clear description of what went wrong.

• code (str) – A unique error code (Exxx format).

• hint (str | None) – An actionable suggestion to resolve the issue.

• severity (Severity) – How critical this error is.

• retryable (bool) – Whether retrying the operation may succeed.

• payload (Dict[str, Any] | None) – Additional metadata for debugging.

• cause (Exception | None) – The original exception that triggered this error.

to_dict()

Serialize error for logging, API responses, or telemetry.

Return type:

dict

class Severity(*values)

Error severity levels.

class ErrorCode(*values)

Every known Astra error code.

Usage:

from astra.errors.codes import ErrorCode
raise LoginFailedError(ErrorCode.AUTH_FAILED)

Common exceptions

• LoginFailedError — login/pairing failed or timed out

• SessionExpiredError — saved session is invalid

• BrowserLimitError — profile locked by another process

• ConnectionLostError — browser or page disconnected

• MessageSendError — cannot deliver a message

Example: graceful handling

from astra.errors import MessageSendError

try:
 await client.send_message(jid, "ping")
except MessageSendError as e:
 # inform user and retry
 logger.warning(e)