Error Handling

Robust exception hierarchy for production reliability.

Exception Hierarchy

TuboxException

├── AuthenticationError

├── UnauthorizedError

├── NotFoundError

│ ├── DocumentNotFoundError

│ ├── CollectionNotFoundError

│ └── DatabaseNotFoundError

├── RateLimitExceededError

├── QuotaExceededError

└── TransactionError

├── TransactionAbortedError

└── TransactionTimeoutError

Common Exceptions

AuthenticationError

Raised when login credentials are invalid or session has expired.

try:
    await client.authenticate(username, password)
except AuthenticationError as e:
    logger.error(f"Login failed: {e.message}")
    # Retry with different credentials or notify user

RateLimitExceededError

Request rate too high. Includes retry_after seconds in error details.

try:
    result = await collection.find(query)
except RateLimitExceededError as e:
    retry_after = e.details.get("retry_after", 60)
    await asyncio.sleep(retry_after)
    # Retry request

TransactionError

Transaction failed to commit or was aborted due to conflicts.

try:
    async with session.start_transaction():
        # ... operations ...
except TransactionAbortedError:
    # Conflict detected, retry with exponential backoff
    await asyncio.sleep(0.1 * (2 ** retry_count))

Best Practices

Catch Specific Exceptions

Always catch specific exceptions rather than the base TuboxException for better error handling.

Implement Retry Logic

Use exponential backoff for transient errors like RateLimitExceededError and TransactionAbortedError.

Log Error Details

All exceptions include message, code, and details attributes for debugging.

Result Classes Configuration

Last updated: Dec 14, 2025

Edit on GitHub Report Issue