Custom Exceptions

Learn the fundamentals of custom exceptions in FastAPI.

🎯 Core Concept

Custom exceptions allow you to define domain-specific errors for your API. They enable you to handle application-specific error scenarios and provide meaningful error responses to clients.

📖 What You'll Learn

In this section, you'll understand:

• How to define custom exception classes

• How to register exception handlers

• How it applies to real-world API development

• Common patterns and best practices

💡 Defining Custom Exceptions

class ItemNotFoundError(Exception):
    def __init__(self, item_id: int):
        self.item_id = item_id
        self.message = f"Item with ID {item_id} not found"

class InsufficientInventoryError(Exception):
    def __init__(self, requested: int, available: int):
        self.requested = requested
        self.available = available
        self.message = f"Need {requested} items but only {available} available"

🔍 Registering Exception Handlers

from fastapi import FastAPI
from fastapi.responses import JSONResponse

app = FastAPI()

@app.exception_handler(ItemNotFoundError)
async def item_not_found_handler(request, exc):
    return JSONResponse(
        status_code=404,
        content={
            "error": "ItemNotFound",
            "detail": exc.message,
            "item_id": exc.item_id
        }
    )

@app.exception_handler(InsufficientInventoryError)
async def insufficient_inventory_handler(request, exc):
    return JSONResponse(
        status_code=400,
        content={
            "error": "InsufficientInventory",
            "detail": exc.message,
            "requested": exc.requested,
            "available": exc.available
        }
    )

💼 Real-World Example

class UserAlreadyExistsError(Exception):
    def __init__(self, email: str):
        self.email = email
        self.message = f"User with email {email} already exists"

@app.exception_handler(UserAlreadyExistsError)
async def user_exists_handler(request, exc):
    return JSONResponse(
        status_code=409,
        content={"error": "UserAlreadyExists", "detail": exc.message}
    )

@app.post("/users/")
async def create_user(user: UserCreate):
    if db.user_exists(user.email):
        raise UserAlreadyExistsError(user.email)
    return db.create_user(user)

How it applies to real-world API development

Custom exceptions are essential for:

• **E-commerce**: Handle inventory, payment, and order-specific errors

• **SaaS platforms**: Manage subscription, quota, and billing errors

• **Authentication systems**: Define authentication, authorization, and session errors

• **Data processing**: Handle validation, transformation, and sync errors

Example - Payment processing:

class PaymentFailedError(Exception):
    def __init__(self, reason: str):
        self.reason = reason

@app.exception_handler(PaymentFailedError)
async def payment_failed_handler(request, exc):
    logger.error(f"Payment failed: {exc.reason}")
    return JSONResponse(status_code=402, content={"error": exc.reason})

@app.post("/checkout")
async def checkout(order: Order):
    if not validate_card(order.card):
        raise PaymentFailedError("Invalid card number")
    process_payment(order)
    return {"status": "success"}

Common patterns and best practices

• ✅ Create exception classes for domain-specific errors

• ✅ Include context in exceptions (IDs, amounts, etc.)

• ✅ Register handlers that return appropriate status codes

• ✅ Log exceptions for debugging and monitoring

• ✅ Return structured error responses

• ✅ Don't expose internal implementation details

• ✅ Test exception handlers thoroughly

• ✅ Use inheritance for related exception types

🔑 Key Takeaways

• ✅ Understand the purpose of custom exceptions

• ✅ Know when to apply this pattern

• ✅ Recognize its benefits in real-world scenarios

• ✅ Be prepared to use it in your projects

Ready to explore more? Check out the advanced section for production patterns and edge cases.