Exceptions

jwtlib.exceptions

Authentication and authorization exceptions.

---

Summary

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