Skip to main content

Custom Exceptions — Designing Custom Exception Class Patterns

Built-in exceptions alone are insufficient for clearly expressing domain-specific error conditions. Designing custom exception classes lets you communicate errors precisely and allows callers to handle them with fine-grained control.


The Simplest Custom Exception​

class AppError(Exception):
"""Application base exception"""
pass

class UserNotFoundError(AppError):
"""When a user cannot be found"""
pass

# Usage
raise UserNotFoundError("User ID 42 not found.")

Even just pass is sufficient. The exception name itself communicates the meaning of the error.


Including Additional Attributes and Methods​

Embedding structured information in exceptions lets callers handle errors more precisely.

class ValidationError(Exception):
"""Input validation failure"""

def __init__(
self,
field: str,
value: object,
message: str
) -> None:
self.field = field
self.value = value
self.message = message
# Initialize parent class
super().__init__(f"[{field}] {message} (received: {value!r})")

def to_dict(self) -> dict:
return {
"field": self.field,
"value": self.value,
"message": self.message,
}
try:
raise ValidationError("age", -5, "Age must be 0 or greater")
except ValidationError as e:
print(e) # [age] Age must be 0 or greater (received: -5)
print(e.field) # age
print(e.to_dict()) # {'field': 'age', 'value': -5, ...}

Overriding __str__ and __repr__​

class HttpError(Exception):
"""HTTP error response"""

def __init__(self, status_code: int, detail: str) -> None:
self.status_code = status_code
self.detail = detail
super().__init__(detail)

def __str__(self) -> str:
return f"HTTP {self.status_code}: {self.detail}"

def __repr__(self) -> str:
return (
f"{type(self).__name__}("
f"status_code={self.status_code!r}, "
f"detail={self.detail!r})"
)

err = HttpError(404, "Resource not found")
print(str(err)) # HTTP 404: Resource not found
print(repr(err)) # HttpError(status_code=404, detail='Resource not found')

Designing an Exception Inheritance Hierarchy​

A good exception hierarchy reflects domain boundaries and error severity.

# ── Base exception ──────────────────────────────────────────────
class AppBaseError(Exception):
"""Root of all application exceptions"""
pass

# ── Domain-level classification ─────────────────────────────────
class DatabaseError(AppBaseError):
"""Database-related errors"""
pass

class NetworkError(AppBaseError):
"""Network-related errors"""
pass

class AuthError(AppBaseError):
"""Authentication/authorization errors"""
pass

class ValidationError(AppBaseError):
"""Data validation errors"""
pass

# ── Specific exceptions ──────────────────────────────────────────
class ConnectionError(DatabaseError):
"""DB connection failure"""
pass

class QueryError(DatabaseError):
"""SQL query error"""
def __init__(self, query: str, reason: str) -> None:
self.query = query
self.reason = reason
super().__init__(f"Query failed: {reason}\nQuery: {query}")

class TimeoutError(NetworkError):
"""Request timeout"""
def __init__(self, url: str, timeout: float) -> None:
self.url = url
self.timeout = timeout
super().__init__(f"Timeout ({timeout}s): {url}")

class UnauthorizedError(AuthError):
"""Authentication failure"""
pass

class ForbiddenError(AuthError):
"""Insufficient permissions"""
def __init__(self, resource: str, required_role: str) -> None:
self.resource = resource
self.required_role = required_role
super().__init__(
f"Accessing '{resource}' requires '{required_role}' role"
)

The hierarchy lets callers choose between specific and general exception handling.

def process():
raise QueryError("SELECT * FROM users", "Table not found")

try:
process()
except QueryError as e:
print(f"SQL error handling: {e.query}") # Specific handling
except DatabaseError:
print("General DB error handling") # Generic handling
except AppBaseError:
print("App error handling") # Top-level handling

Practical Example — API Error Class Hierarchy​

An exception system suitable for a real REST API server.

from http import HTTPStatus
from typing import Any

class APIError(Exception):
"""Base class for API errors"""

status_code: int = 500
error_code: str = "INTERNAL_ERROR"

def __init__(
self,
message: str,
detail: Any = None,
headers: dict[str, str] | None = None,
) -> None:
self.message = message
self.detail = detail
self.headers = headers or {}
super().__init__(message)

def to_response(self) -> dict[str, Any]:
"""Return API error response dictionary"""
response: dict[str, Any] = {
"error": self.error_code,
"message": self.message,
}
if self.detail is not None:
response["detail"] = self.detail
return response

def __repr__(self) -> str:
return (
f"{type(self).__name__}("
f"status={self.status_code}, "
f"code={self.error_code!r}, "
f"message={self.message!r})"
)


class BadRequestError(APIError):
"""400 Bad Request"""
status_code = 400
error_code = "BAD_REQUEST"


class ValidationAPIError(BadRequestError):
"""400 — Input validation failure"""
error_code = "VALIDATION_ERROR"

def __init__(self, errors: list[dict[str, str]]) -> None:
self.errors = errors
super().__init__(
message="Input validation failed.",
detail=errors,
)

def to_response(self) -> dict[str, Any]:
resp = super().to_response()
resp["errors"] = self.errors
return resp


class NotFoundError(APIError):
"""404 Not Found"""
status_code = 404
error_code = "NOT_FOUND"

def __init__(self, resource: str, identifier: Any) -> None:
self.resource = resource
self.identifier = identifier
super().__init__(
message=f"{resource} '{identifier}' not found.",
detail={"resource": resource, "id": identifier},
)


class ConflictError(APIError):
"""409 Conflict"""
status_code = 409
error_code = "CONFLICT"


class RateLimitError(APIError):
"""429 Too Many Requests"""
status_code = 429
error_code = "RATE_LIMIT_EXCEEDED"

def __init__(self, retry_after: int) -> None:
self.retry_after = retry_after
super().__init__(
message="Request limit exceeded.",
headers={"Retry-After": str(retry_after)},
)


# FastAPI / Flask style exception handler
def handle_api_error(exc: APIError) -> dict[str, Any]:
return {
"status": exc.status_code,
"body": exc.to_response(),
"headers": exc.headers,
}
# Usage examples
def get_user(user_id: int) -> dict:
users = {1: {"name": "Alice"}}
if user_id not in users:
raise NotFoundError("User", user_id)
return users[user_id]

def create_user(data: dict) -> dict:
errors = []
if not data.get("name"):
errors.append({"field": "name", "message": "Required field"})
if not data.get("email"):
errors.append({"field": "email", "message": "Required field"})
if errors:
raise ValidationAPIError(errors)
return {"id": 42, **data}

# Handling
try:
user = get_user(99)
except NotFoundError as e:
response = handle_api_error(e)
print(response)
# {'status': 404, 'body': {'error': 'NOT_FOUND', ...}, 'headers': {}}

dataclass-based Exceptions (Python 3.10+)​

from dataclasses import dataclass, field

@dataclass
class BusinessError(Exception):
"""Business logic error"""
code: str
message: str
context: dict = field(default_factory=dict)

def __post_init__(self):
# Initialize Exception (supports str(exception))
super().__init__(self.message)

def __str__(self) -> str:
return f"[{self.code}] {self.message}"

# Usage
raise BusinessError(
code="INSUFFICIENT_BALANCE",
message="Insufficient balance.",
context={"required": 10000, "available": 3000}
)

Expert Tips​

Tip 1 — No need for from __future__ import annotations in exception classes

Exception classes themselves need to be evaluated at runtime, so PEP 563 lazy evaluation is not needed.

Tip 2 — Always expose a base exception if you're writing a library

# mylib/exceptions.py
class MyLibError(Exception):
"""Base class for all mylib exceptions"""
pass

# Users can catch all mylib exceptions at once
try:
mylib.do_something()
except mylib.MyLibError:
pass

Tip 3 — Write exception messages for developers

# Bad: vague message
raise ValueError("Error")

# Good: include cause, value, and resolution hint
raise ValueError(
f"Age value {age!r} is invalid. "
f"Enter an integer between 0 and 150."
)

Tip 4 — Automate exception registration with __init_subclass__

class RegisteredError(Exception):
_registry: dict[str, type] = {}

def __init_subclass__(cls, code: str = "", **kwargs):
super().__init_subclass__(**kwargs)
if code:
RegisteredError._registry[code] = cls

class NotFoundError(RegisteredError, code="NOT_FOUND"):
pass

class AuthError(RegisteredError, code="UNAUTHORIZED"):
pass

# Look up exception class by code
exc_class = RegisteredError._registry["NOT_FOUND"]
raise exc_class("Not found")