Python Tutorial — Learn Python Step by Step

Python Custom Exceptions

Custom exceptions let you define meaningful error types specific to your application. They make error handling clearer and help callers understand what went wrong.

Creating Basic Custom Exceptions

# Simplest custom exception — inherit from Exception
class ValidationError(Exception):
    pass

class NotFoundError(Exception):
    pass

# Raise and catch custom exceptions
def find_user(user_id):
    users = {1: "Alice", 2: "Bob"}
    if user_id not in users:
        raise NotFoundError(f"User {user_id} not found")
    return users[user_id]

try:
    user = find_user(99)
except NotFoundError as e:
    print(e)  # User 99 not found

Custom Exceptions with Extra Data

# Add attributes to carry context about the error
class ValidationError(Exception):
    def __init__(self, field, message, value=None):
        self.field = field
        self.message = message
        self.value = value
        super().__init__(f"{field}: {message}")

    def to_dict(self):
        return {"field": self.field, "error": self.message, "value": self.value}

# Usage
def validate_age(age):
    if not isinstance(age, int):
        raise ValidationError("age", "Must be an integer", age)
    if age < 0 or age > 150:
        raise ValidationError("age", "Must be between 0 and 150", age)
    return age

try:
    validate_age(-5)
except ValidationError as e:
    print(e)           # age: Must be between 0 and 150
    print(e.field)     # age
    print(e.value)     # -5
    print(e.to_dict()) # {"field": "age", "error": "Must be...", "value": -5}

Exception Hierarchies

# Create a hierarchy for your application
class AppError(Exception):
    """Base exception for the application."""
    pass

class DatabaseError(AppError):
    """Database-related errors."""
    pass

class ConnectionError(DatabaseError):
    """Cannot connect to database."""
    pass

class QueryError(DatabaseError):
    """Invalid or failed query."""
    pass

class AuthError(AppError):
    """Authentication/authorization errors."""
    pass

class InvalidCredentialsError(AuthError):
    pass

class PermissionDeniedError(AuthError):
    pass

# Catch at different levels of specificity
try:
    authenticate(user, password)
except InvalidCredentialsError:
    print("Wrong username or password")
except AuthError:
    print("Authentication failed")
except AppError:
    print("Application error occurred")

Practical Example: API Service

# Real-world pattern for a web service
class APIError(Exception):
    """Base API exception with HTTP status code."""
    status_code = 500

    def __init__(self, message, details=None):
        self.message = message
        self.details = details or {}
        super().__init__(message)

    def to_response(self):
        return {
            "error": type(self).__name__,
            "message": self.message,
            "details": self.details,
        }

class BadRequestError(APIError):
    status_code = 400

class UnauthorizedError(APIError):
    status_code = 401

class NotFoundError(APIError):
    status_code = 404

class RateLimitError(APIError):
    status_code = 429

    def __init__(self, retry_after=60):
        self.retry_after = retry_after
        super().__init__(f"Rate limit exceeded. Retry after {retry_after}s")

# Usage in request handler
def get_user(user_id):
    if not is_authenticated():
        raise UnauthorizedError("Login required")
    user = db.find_user(user_id)
    if user is None:
        raise NotFoundError(f"User {user_id} not found")
    return user

try:
    user = get_user(42)
except APIError as e:
    response = e.to_response()
    response["status"] = e.status_code
    print(response)

Exception Chaining

# Use "from" to chain exceptions — preserves the original cause
class ConfigError(Exception):
    pass

def load_config(path):
    try:
        with open(path) as f:
            import json
            return json.load(f)
    except FileNotFoundError as e:
        raise ConfigError(f"Config file missing: {path}") from e
    except json.JSONDecodeError as e:
        raise ConfigError(f"Invalid JSON in {path}") from e

try:
    config = load_config("settings.json")
except ConfigError as e:
    print(e)            # Config file missing: settings.json
    print(e.__cause__)  # [Errno 2] No such file or directory: ...

• Always inherit from Exception (not BaseException) for custom exceptions.
• Add attributes to carry context (field names, error codes, values) with the exception.
• Create exception hierarchies so callers can catch at the appropriate level of specificity.
• Use raise ... from original to chain exceptions and preserve the root cause.
• Name exceptions ending in Error to follow Python conventions.