Exceptions

jwtlib.exceptions

Summary

Authentication and authorization exceptions.

This module defines the exception hierarchy used throughout the authentication library to represent authentication, authorization, and service-level failures.

All exceptions inherit from AuthError, allowing consumers to catch authentication-related failures broadly or handle specific cases selectively.

Classes

AuthError

Bases: Exception

Base authentication and authorization error.

Notes

Guarantees:

- All authentication-related exceptions raised by this library
  inherit from this class.
- Consumers may catch this exception to handle all auth failures
  uniformly.

AuthServiceUnavailable

Bases: AuthError

Raised when the authentication service cannot be reached.

Notes

Guarantees:

- Indicates a network failure, timeout, or unexpected error while
  communicating with the auth service.

InvalidAuthorizationHeader

Bases: AuthError

Raised when the Authorization header is missing or incorrectly formatted.

Notes

Guarantees:

- Indicates that the header is not present or does not follow the
  expected `Bearer <token>` format.

InvalidToken

Bases: AuthError

Raised when a JWT is missing, malformed, expired, or invalid.

Notes

Guarantees:

- This error indicates that the provided token cannot be used to
  authenticate a request.

NotAuthenticated

Bases: AuthError

Raised when authentication is required but no user context is present.

Notes

Guarantees:

- Typically used when attempting to access a protected operation
  without an authenticated user.

UserNotFound

Bases: AuthError

Raised when a valid token does not map to an existing user.

Notes

Guarantees:

- Indicates that authentication succeeded at the token level, but
  the associated user record could not be resolved.