AvnologyIdError (base)
  +-- AuthError
  |    +-- InvalidCredentialsError
  |    +-- AccountLockedError (retry_after: int)
  |    +-- AccountDisabledError
  |    +-- MfaRequiredError (flow_id: str, available_methods: list[str])
  |    +-- InvalidCodeError (attempts_remaining: int)
  |    +-- ExpiredFlowError
  |    +-- PasswordBreachedError
  |    +-- PasswordTooWeakError (reason: str)
  |    +-- DuplicateAccountError
  +-- OAuthError
  |    +-- InvalidGrantError
  |    +-- InvalidClientError
  |    +-- InvalidScopeError
  |    +-- InsufficientScopeError
  +-- ApiError
  |    +-- NotFoundError
  |    +-- ForbiddenError
  |    +-- UnauthorizedError
  |    +-- ValidationError (field_errors: list[FieldError])
  |    +-- ConflictError
  +-- RateLimitError (retry_after: int, limit: int, remaining: int)
  +-- NetworkError
  +-- TimeoutError

class AvnologyIdError(Exception):
    code: str              # "AVNOLOGY_AUTH_001"
    status_code: int | None
    message: str
    request_id: str | None
    details: dict[str, Any]

from avnology_id.errors import (
    InvalidCredentialsError,
    AccountLockedError,
    MfaRequiredError,
    RateLimitError,
    NotFoundError,
    ValidationError,
)

try:
    session = client.login(email=email, password=password)
except InvalidCredentialsError:
    print("Invalid email or password")
except AccountLockedError as e:
    print(f"Account locked for {e.retry_after} seconds")
except MfaRequiredError as e:
    handle_mfa(e.flow_id, e.available_methods)
except RateLimitError as e:
    time.sleep(e.retry_after)
    retry()

from avnology_id.errors import AvnologyIdError, AuthError

try:
    result = client.admin.get_user(user_id="usr_nonexistent")
except AuthError:
    print("Authentication problem")
except AvnologyIdError as e:
    print(f"API error: {e.code} - {e.message}")
    if e.request_id:
        print(f"Request ID for support: {e.request_id}")

from avnology_id.errors import ValidationError

try:
    client.register(email="bad-email", password="short")
except ValidationError as e:
    for field_error in e.field_errors:
        print(f"  {field_error.field}: {field_error.message}")
    # Output:
    #   email: Invalid email format
    #   password: Must be at least 8 characters