Exceptions¶

All exceptions raised by tortoise-auth live in the tortoise_auth.exceptions module and inherit from a single base class, TortoiseAuthError. This makes it straightforward to catch everything the library can throw with one except clause while still allowing fine-grained handling when you need it.

Hierarchy¶

TortoiseAuthError
├── AuthenticationError
├── InvalidPasswordError
├── InvalidHashError
├── ConfigurationError
├── EventError
├── RateLimitError
├── TokenError
│   ├── TokenExpiredError
│   ├── TokenInvalidError
│   └── TokenRevokedError
├── SigningError
│   ├── SignatureExpiredError
│   └── BadSignatureError
└── OnboardingError
    ├── OnboardingSessionExpiredError
    ├── OnboardingSessionInvalidError
    ├── OnboardingStepError
    └── OnboardingFlowCompleteError

Exception reference¶

TortoiseAuthError¶

Detail	Value
Parent	`Exception`
Module	`tortoise_auth.exceptions`

Base class for every exception raised by tortoise-auth. Catch this when you want a single handler for all library errors.

from tortoise_auth.exceptions import TortoiseAuthError

try:
    await auth.login(email, password)
except TortoiseAuthError as exc:
    log.error("tortoise-auth error: %s", exc)

AuthenticationError¶

Detail	Value
Parent	`TortoiseAuthError`

Raised when AuthService.login() or AuthService.authenticate() fails. The error message is intentionally generic ("Invalid credentials") to avoid leaking information about whether the email exists or the password was wrong.

InvalidPasswordError¶

Detail	Value
Parent	`TortoiseAuthError`
Attribute	`errors: list[str]`

Raised when a password does not satisfy the configured validators. The errors attribute contains one human-readable string per failed validation rule. The default str() representation joins them with "; ".

from tortoise_auth.exceptions import InvalidPasswordError

try:
    await user.set_password("short")
except InvalidPasswordError as exc:
    for message in exc.errors:
        print(message)
    # "Password must be at least 8 characters"
    # "Password must contain at least one uppercase letter"

InvalidHashError¶

Detail	Value
Parent	`TortoiseAuthError`
Attribute	`hash: str`

Raised when a stored password hash cannot be recognised by any of the configured hashers. This typically indicates data corruption or a hash produced by an algorithm that is no longer enabled. The hash attribute contains the unrecognised value.

ConfigurationError¶

Detail	Value
Parent	`TortoiseAuthError`

Raised when configure() receives an invalid AuthConfig. Common causes include an unresolvable user_model path or mutually exclusive options.

from tortoise_auth import AuthConfig, configure
from tortoise_auth.exceptions import ConfigurationError

try:
    config = AuthConfig(user_model="models.User")
    config.validate()
except ConfigurationError as exc:
    print(exc)  # descriptive message about what is wrong

EventError¶

Detail	Value
Parent	`TortoiseAuthError`
Attribute	`event_name: str`
Attribute	`handler_name: str`
Attribute	`original: Exception`

Raised when a registered event handler raises an unhandled exception. The three attributes let you identify exactly which handler failed, for which event, and what the underlying error was.

from tortoise_auth.exceptions import EventError

try:
    await auth.login(email, password)
except EventError as exc:
    log.error(
        "Handler %r for event %r failed: %s",
        exc.handler_name,
        exc.event_name,
        exc.original,
    )

TokenError¶

Detail	Value
Parent	`TortoiseAuthError`

Base class for all token-related errors. Catch this when you want a single handler for any token problem -- expired, invalid, or revoked -- without distinguishing between them.

from tortoise_auth.exceptions import TokenError

try:
    user = await auth.authenticate(access_token)
except TokenError:
    # return 401 regardless of the specific reason
    ...

TokenExpiredError¶

Detail	Value
Parent	`TokenError`

Raised when a token's expiration time is in the past. The client should use its refresh token to obtain a new access token.

TokenInvalidError¶

Detail	Value
Parent	`TokenError`

Raised when a token is structurally invalid (cannot be decoded) or its token_type claim does not match the expected type. For example, passing a refresh token where an access token is required triggers this error.

TokenRevokedError¶

Detail	Value
Parent	`TokenError`

Raised when a token that has been explicitly revoked (via logout() or logout_all()) is presented for authentication or refresh.

SigningError¶

Detail	Value
Parent	`TortoiseAuthError`

Base class for errors related to the low-level HMAC signing utility. Catch this when you want a single handler for any signing problem.

from tortoise_auth.exceptions import SigningError

try:
    data = signer.unsign(token)
except SigningError:
    # signed token is invalid or expired
    ...

SignatureExpiredError¶

Detail	Value
Parent	`SigningError`

Raised when a signed token has exceeded its max_age. The signature itself is valid, but the token is no longer accepted because it is too old.

BadSignatureError¶

Detail	Value
Parent	`SigningError`

Raised when the HMAC signature on a token does not match the expected value. This means the token has been tampered with or was signed with a different secret.

OnboardingError¶

Detail	Value
Parent	`TortoiseAuthError`

Base class for all onboarding flow errors. Catch this when you want a single handler for any onboarding problem.

OnboardingSessionExpiredError¶

Detail	Value
Parent	`OnboardingError`
Attribute	`session_id: str`

Raised when an onboarding session has exceeded its configured lifetime (onboarding_session_lifetime). The user must start a new onboarding flow.

OnboardingSessionInvalidError¶

Detail	Value
Parent	`OnboardingError`
Attribute	`reason: str`

Raised when an onboarding session cannot be found, has been invalidated (e.g., because a newer session was started for the same email), or is otherwise unusable. The reason attribute provides a human-readable explanation.

OnboardingStepError¶

Detail	Value
Parent	`OnboardingError`
Attribute	`step_name: str`
Attribute	`errors: list[str]`

Raised when an onboarding step fails. The step_name identifies which step failed and the errors list contains one or more human-readable error messages.

OnboardingFlowCompleteError¶

Detail	Value
Parent	`OnboardingError`

Raised when attempting to advance() or resume() a flow that has already been completed. The client should use the auth tokens it received at completion.

Catch patterns¶

Use the hierarchy to write precise or broad exception handlers depending on your needs.

Catch everything from the library¶

from tortoise_auth.exceptions import TortoiseAuthError

try:
    ...
except TortoiseAuthError:
    ...

Catch all token errors¶

from tortoise_auth.exceptions import TokenError

try:
    user = await auth.authenticate(token)
except TokenError:
    # covers TokenExpiredError, TokenInvalidError, TokenRevokedError
    ...

Catch all signing errors¶

from tortoise_auth.exceptions import SigningError

try:
    data = signer.unsign(token)
except SigningError:
    # covers SignatureExpiredError, BadSignatureError
    ...

Catch all onboarding errors¶

from tortoise_auth.exceptions import OnboardingError

try:
    result = await onboarding.advance(token, data)
except OnboardingError:
    # covers expired, invalid, step errors, and flow-complete
    ...

Distinguish between onboarding failure reasons¶

from tortoise_auth.exceptions import (
    OnboardingFlowCompleteError,
    OnboardingSessionExpiredError,
    OnboardingSessionInvalidError,
)

try:
    result = await onboarding.advance(token, data)
except OnboardingSessionExpiredError:
    # 410 Gone — prompt user to start over
    ...
except OnboardingSessionInvalidError:
    # 404 Not Found — session not found or invalidated
    ...
except OnboardingFlowCompleteError:
    # 409 Conflict — flow already completed
    ...

Distinguish between token failure reasons¶

from tortoise_auth.exceptions import (
    TokenExpiredError,
    TokenInvalidError,
    TokenRevokedError,
)

try:
    user = await auth.authenticate(token)
except TokenExpiredError:
    # prompt the client to refresh
    ...
except TokenRevokedError:
    # force a full re-login
    ...
except TokenInvalidError:
    # reject the request outright
    ...