How to create custom exceptions in Python

Why Custom Exceptions?

Custom exceptions make your code more readable and your APIs easier to use. They let callers catch specific errors without relying on fragile string matching.

Basic Custom Exception

Simply inherit from Exception or a built-in subclass:

class ValidationError(Exception):
    pass

class PaymentError(Exception):
    def __init__(self, message, amount):
        super().__init__(message)
        self.amount = amount

Building Hierarchies

Organize exceptions hierarchically to allow granular or broad catching:

class AppError(Exception):
    pass

class DatabaseError(AppError):
    pass

class ConnectionError(DatabaseError):
    pass

For patterns on catching and managing these exceptions gracefully, see Python error handling try except. If you are building a library, combining custom exceptions with Python logging setup ensures errors are captured with full context.

Best Practices

Keep exception names descriptive, provide useful attributes, and document when each is raised. Avoid catching Exception unless you are logging and re-raising.