Error Codes

Astra uses structured error codes so you always know exactly what went wrong and what to do about it. Every exception is a subclass of AstraError and carries a human-readable code, message, hint, and retry flag.

Code format

All codes follow the pattern Exxxx where the first digit identifies the category:

Catching errors

You can catch specific error types:

from astra.errors import MessageSendError, RateLimitedError

try:
 await client.chat.send_message(jid, "Hello")
except RateLimitedError as e:
 print(f"[{e.code}] Rate limited. Retry: {e.retryable}")
 print(f"Hint: {e.hint}")
 await asyncio.sleep(30)
except MessageSendError as e:
 print(f"[{e.code}] Failed: {e.message}")

Or catch the base class for a general handler:

from astra.errors import AstraError

try:
 await do_something()
except AstraError as e:
 log.error(f"[{e.code}] {e.message} | hint: {e.hint}")
 if e.retryable:
  await retry(do_something)

Common error codes

Authentication (E1xxx)

Connection (E2xxx)

Messaging (E3xxx)

Protocol (E7xxx)

Full reference

For the complete list of all 71 error codes, see the ERROR_CODES.md file in the repository.

Error anatomy

Every AstraError has these attributes:

error.code  # "E3001"
error.message  # "Message failed to send"
error.hint  # "Check the JID format and your connection"
error.severity # Severity.ERROR
error.retryable # True
error.cause  # Original exception, if any
error.to_dict() # Serializable dict for logging / APIs