CtrlK

Community Documentation Log in Get started

maria/fastapi

FastAPI framework with Pydantic v2 patterns, PII sanitisation, and practical workflows

94%

Overall

Review — 94%

Quality of skill definitions

Evaluation

Agent success when using this tile

Exception Handling

Name: maria/fastapi
Author: maria

FastAPI provides comprehensive exception handling capabilities that integrate with HTTP status codes, automatic error responses, and custom exception handlers. The framework includes built-in exceptions for common scenarios and allows for custom exception handling patterns.

Capabilities

HTTP Exception

The primary exception class for handling HTTP errors with proper status codes and response formatting.

class HTTPException(Exception):
    def __init__(
        self,
        status_code: int,
        detail: Any = None,
        headers: Dict[str, str] = None
    ) -> None:
        """
        HTTP exception with status code and detail message.
        
        Parameters:
        - status_code: HTTP status code (400, 401, 404, 500, etc.)
        - detail: Error detail message or structured data
        - headers: Additional HTTP headers to include in error response
        """
        self.status_code = status_code
        self.detail = detail
        self.headers = headers

WebSocket Exception

Exception class specifically for WebSocket connection errors.

class WebSocketException(Exception):
    def __init__(
        self,
        code: int,
        reason: str = None
    ) -> None:
        """
        WebSocket error exception.
        
        Parameters:
        - code: WebSocket close code (1000-4999)
        - reason: Human-readable close reason
        """
        self.code = code
        self.reason = reason

FastAPI Error

Generic runtime error exception for FastAPI framework issues.

class FastAPIError(Exception):
    def __init__(self, message: str = None) -> None:
        """
        Generic FastAPI runtime error.
        
        Parameters:
        - message: Error message describing the issue
        """
        self.message = message

Validation Exceptions

Exception classes for handling request and response validation errors with detailed error information.

class ValidationException(Exception):
    def __init__(self, errors: List[dict]) -> None:
        """
        Base validation error exception.
        
        Parameters:
        - errors: List of validation error dictionaries
        """
        self.errors = errors

class RequestValidationError(ValidationException):
    def __init__(self, errors: List[ErrorWrapper]) -> None:
        """
        Request validation error with detailed error information.
        
        Parameters:
        - errors: List of Pydantic ErrorWrapper objects containing
                 field-specific validation error details
        """
        self.errors = errors
        self.body = getattr(errors, "body", None)

class WebSocketRequestValidationError(ValidationException):
    def __init__(self, errors: List[ErrorWrapper]) -> None:
        """
        WebSocket request validation error.
        
        Parameters:
        - errors: List of Pydantic ErrorWrapper objects for WebSocket
                 parameter validation failures
        """
        self.errors = errors

class ResponseValidationError(ValidationException):
    def __init__(self, errors: List[ErrorWrapper]) -> None:
        """
        Response validation error for response model validation failures.
        
        Parameters:
        - errors: List of Pydantic ErrorWrapper objects containing
                 response validation error details
        """
        self.errors = errors

Exception Handler Decorator

Decorator method for registering custom exception handlers on FastAPI and APIRouter instances.

def exception_handler(
    self,
    exc_class_or_status_code: Union[int, Type[Exception]]
) -> Callable[[Callable], Callable]:
    """
    Decorator for adding exception handlers.

    Parameters:
    - exc_class_or_status_code: Exception class or HTTP status code to handle

    Returns:
    Decorator function for exception handler registration
    """

Exception Handler Function Type

Type signature for custom exception handler functions.

async def exception_handler_function(
    request: Request,
    exc: Exception
) -> Response:
    """
    Exception handler function signature.
    
    Parameters:
    - request: HTTP request object
    - exc: Exception instance that was raised
    
    Returns:
    Response object to send to client
    """

Usage Examples

Basic HTTP Exception Handling

from fastapi import FastAPI, HTTPException, status

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    if item_id == 0:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Item not found"
        )
    if item_id < 0:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail="Item ID must be positive",
            headers={"X-Error": "Invalid item ID"}
        )
    return {"item_id": item_id, "name": f"Item {item_id}"}

Custom Exception Handler

from fastapi import FastAPI, Request, HTTPException
from fastapi.responses import JSONResponse
from fastapi.exceptions import RequestValidationError
from starlette.exceptions import HTTPException as StarletteHTTPException

app = FastAPI()

@app.exception_handler(StarletteHTTPException)
async def http_exception_handler(request: Request, exc: StarletteHTTPException):
    return JSONResponse(
        status_code=exc.status_code,
        content={
            "error": "HTTP Exception",
            "message": exc.detail,
            "path": request.url.path,
            "method": request.method
        }
    )

@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc: RequestValidationError):
    return JSONResponse(
        status_code=422,
        content={
            "error": "Validation Error",
            "message": "Invalid request data",
            "details": exc.errors(),
            "body": exc.body
        }
    )

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    if item_id == 42:
        raise HTTPException(status_code=418, detail="I'm a teapot")
    return {"item_id": item_id}

Custom Exception Classes

from fastapi import FastAPI, Request, HTTPException
from fastapi.responses import JSONResponse

app = FastAPI()

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

class InsufficientPermissionsError(Exception):
    def __init__(self, required_role: str, user_role: str):
        self.required_role = required_role
        self.user_role = user_role
        self.message = f"Required role: {required_role}, user role: {user_role}"
        super().__init__(self.message)

class BusinessLogicError(Exception):
    def __init__(self, message: str, error_code: str):
        self.message = message
        self.error_code = error_code
        super().__init__(self.message)

# Exception handlers
@app.exception_handler(ItemNotFoundError)
async def item_not_found_handler(request: Request, exc: ItemNotFoundError):
    return JSONResponse(
        status_code=404,
        content={
            "error": "Item Not Found",
            "message": exc.message,
            "item_id": exc.item_id
        }
    )

@app.exception_handler(InsufficientPermissionsError)
async def insufficient_permissions_handler(request: Request, exc: InsufficientPermissionsError):
    return JSONResponse(
        status_code=403,
        content={
            "error": "Insufficient Permissions",
            "message": exc.message,
            "required_role": exc.required_role,
            "user_role": exc.user_role
        }
    )

@app.exception_handler(BusinessLogicError)
async def business_logic_handler(request: Request, exc: BusinessLogicError):
    return JSONResponse(
        status_code=422,
        content={
            "error": "Business Logic Error",
            "message": exc.message,
            "error_code": exc.error_code
        }
    )

# Routes using custom exceptions
@app.get("/items/{item_id}")
async def get_item(item_id: int):
    if item_id == 999:
        raise ItemNotFoundError(item_id)
    return {"item_id": item_id, "name": f"Item {item_id}"}

@app.delete("/items/{item_id}")
async def delete_item(item_id: int, user_role: str = "user"):
    if user_role != "admin":
        raise InsufficientPermissionsError("admin", user_role)
    if item_id <= 0:
        raise BusinessLogicError("Cannot delete items with non-positive IDs", "INVALID_ID")
    return {"message": f"Item {item_id} deleted"}