← FastAPI

Error Handling & Validation Errors

Middleware & CORS

← Error Handling & Validation Errors

Select a question from the sidebar

12 questions in this topic

Question 1 / 12

How does HTTPException work in FastAPI?

HTTPException is FastAPI's built-in way to return HTTP error responses from endpoints and dependencies. It immediately stops request processing and sends a JSON error response.

How it works:

You raise HTTPException(status_code=..., detail=...) anywhere in your endpoint or dependency
FastAPI catches it and returns a JSON response with the given status code
The detail field can be a string, dict, or list -- it is JSON-serialized automatically
An optional headers dict adds extra HTTP headers to the error response

Parameters:

status_code (int): The HTTP status code (400, 401, 403, 404, 422, 500, etc.)
detail (Any): The error message or structured error data
headers (dict | None): Additional response headers (e.g., WWW-Authenticate for 401)

Default response format:

{"detail": "your error message"}

Common status codes:

Code	Meaning	Use case
400	Bad Request	Invalid input that passes validation
401	Unauthorized	Missing or invalid auth
403	Forbidden	Authenticated but not authorized
404	Not Found	Resource does not exist
409	Conflict	Duplicate resource
422	Unprocessable Entity	Validation error (FastAPI's default)

Pseudo Code

# Simple string error
raise HTTPException(status_code=404, detail="Item not found")

# Structured error with dict
raise HTTPException(status_code=400, detail={"field": "email", "error": "invalid"})

# With custom headers
raise HTTPException(
    status_code=401,
    detail="Token expired",
    headers={"WWW-Authenticate": "Bearer"},
)

Code

from fastapi import FastAPI, HTTPException, status
from fastapi.testclient import TestClient

app = FastAPI()

# Simulated database
ITEMS = {1: {"name": "Widget", "price": 9.99}, 2: {"name": "Gadget", "price": 24.99}}

@app.get("/items/{item_id}")
def get_item(item_id: int):
    if item_id < 0:
        # String detail
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail="Item ID must be positive",
        )
    if item_id not in ITEMS:
        # Structured detail (dict)
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail={"error": "not_found", "item_id": item_id},
        )
    return ITEMS[item_id]

@app.delete("/items/{item_id}")
def delete_item(item_id: int):
    if item_id not in ITEMS:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Item not found",
            headers={"X-Error-Code": "ITEM_NOT_FOUND"},
        )
    return {"deleted": item_id}

# --- Test ---
client = TestClient(app)

# Valid item
resp = client.get("/items/1")
print(f"200: {resp.json()}")

# Negative ID -> 400
resp = client.get("/items/-1")
print(f"400: {resp.status_code} {resp.json()}")

# Not found -> 404 with structured detail
resp = client.get("/items/999")
print(f"404: {resp.status_code} {resp.json()}")

# Delete not found -> custom header
resp = client.delete("/items/999")
print(f"Header: {resp.headers.get('X-Error-Code')}")

200: {'name': 'Widget', 'price': 9.99}
400: 400 {'detail': 'Item ID must be positive'}
404: 404 {'detail': {'error': 'not_found', 'item_id': 999}}
Header: ITEM_NOT_FOUND

Key Points

•HTTPException immediately stops execution and returns a JSON error response
•detail can be a string, dict, or list -- it is JSON-serialized automatically
•Use status module constants (status.HTTP_404_NOT_FOUND) for readability
•The optional headers parameter adds custom HTTP headers to the error response

Gotchas

•HTTPException is raised, not returned -- use raise, not return
•detail is the only field in the default JSON response body -- for richer error formats, use custom exception handlers
•FastAPI's HTTPException extends Starlette's and adds the detail parameter to accept any JSON-serializable type, not just strings

raise HTTPException(status_code=404, detail="Not found") immediately returns a JSON error response {"detail": "Not found"} with the given status code. The detail can be a string, dict, or list. Use headers to add custom response headers.

•raise HTTPException stops execution and returns JSON {"detail": ...}

from fastapi import FastAPI, HTTPException, status

app = FastAPI()

@app.get("/items/{item_id}")
def get_item(item_id: int):
    if item_id not in db:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Item not found",
        )
    return db[item_id]

HTTPException is raised, not returned -- use raise, not return

Question 2 / 12

How do you create custom exception handlers?

Custom exception handlers let you control exactly how exceptions are turned into HTTP responses. Instead of the default {"detail": ...} format, you can return any response structure.

How to register a handler:

Use @app.exception_handler(ExceptionClass) to register a function that handles a specific exception type. The function receives the Request and the exception instance.

Handler signature:

async def handler(request: Request, exc: MyException) -> Response:

What you can customize:

Response body structure (add error codes, timestamps, request IDs)
Response content type (JSON, HTML, plain text)
Status code
Response headers

Execution order:

Exception is raised in endpoint or dependency
FastAPI looks for a handler registered for that exact exception class
If found, it calls the handler and returns its response
If not found, it checks parent exception classes
If no handler matches, FastAPI returns a default 500 Internal Server Error

Built-in exceptions you can override:

HTTPException: Override the default JSON error format
RequestValidationError: Override validation error responses
StarletteHTTPException: Starlette's base HTTP exception

Pseudo Code

class ItemNotFoundError(Exception):
    def __init__(self, item_id: int):
        self.item_id = item_id

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

# In endpoint:
raise ItemNotFoundError(item_id=42)

Code

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
from fastapi.testclient import TestClient
from datetime import datetime, timezone

app = FastAPI()

# --- Custom exception classes ---
class AppException(Exception):
    """Base exception for the application."""
    def __init__(self, code: str, message: str, status_code: int = 400):
        self.code = code
        self.message = message
        self.status_code = status_code

class ItemNotFoundError(AppException):
    def __init__(self, item_id: int):
        super().__init__(
            code="ITEM_NOT_FOUND",
            message=f"Item {item_id} does not exist",
            status_code=404,
        )
        self.item_id = item_id

class InsufficientStockError(AppException):
    def __init__(self, item_id: int, available: int):
        super().__init__(
            code="INSUFFICIENT_STOCK",
            message=f"Only {available} units available",
            status_code=409,
        )

# --- Register handler for the base exception class ---
@app.exception_handler(AppException)
async def app_exception_handler(request: Request, exc: AppException):
    return JSONResponse(
        status_code=exc.status_code,
        content={
            "error": {
                "code": exc.code,
                "message": exc.message,
                "timestamp": datetime.now(timezone.utc).isoformat(),
                "path": str(request.url.path),
            }
        },
    )

ITEMS = {1: {"name": "Widget", "stock": 5}}

@app.get("/items/{item_id}")
def get_item(item_id: int):
    if item_id not in ITEMS:
        raise ItemNotFoundError(item_id=item_id)
    return ITEMS[item_id]

@app.post("/items/{item_id}/purchase")
def purchase_item(item_id: int, quantity: int = 1):
    if item_id not in ITEMS:
        raise ItemNotFoundError(item_id=item_id)
    if ITEMS[item_id]["stock"] < quantity:
        raise InsufficientStockError(item_id, ITEMS[item_id]["stock"])
    return {"purchased": quantity}

# --- Test ---
client = TestClient(app)

# Not found -> custom error format
resp = client.get("/items/999")
print(f"Status: {resp.status_code}")
error = resp.json()["error"]
print(f"Code: {error['code']}")
print(f"Message: {error['message']}")
print(f"Path: {error['path']}")

# Insufficient stock
resp = client.post("/items/1/purchase?quantity=100")
print(f"Stock error: {resp.status_code} {resp.json()['error']['code']}")

Status: 404
Code: ITEM_NOT_FOUND
Message: Item 999 does not exist
Path: /items/999
Stock error: 409 INSUFFICIENT_STOCK

Key Points

•@app.exception_handler(ExceptionClass) registers a custom handler for that exception type
•The handler receives the Request and exception instance, and must return a Response
•Registering a handler for a base class catches all subclasses too
•Custom handlers let you return structured error formats with codes, timestamps, and paths

Gotchas

•The handler must return a Response object (e.g., JSONResponse) -- it cannot raise another exception
•A handler for a base class catches all subclass exceptions -- register more specific handlers first if you need different behavior
•Custom exception handlers do not catch exceptions in middleware -- only in endpoints and dependencies

Use @app.exception_handler(MyException) to register a function that converts exceptions into custom JSON responses. The handler receives request and exc, and must return a Response (e.g., JSONResponse). A handler for a base class catches all subclasses.

•@app.exception_handler registers a function to convert exceptions to responses

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

app = FastAPI()

class NotFoundError(Exception):
    def __init__(self, resource: str, id: int):
        self.resource = resource
        self.id = id

@app.exception_handler(NotFoundError)
async def not_found_handler(request: Request, exc: NotFoundError):
    return JSONResponse(
        status_code=404,
        content={"error": f"{exc.resource} {exc.id} not found"},
    )

The handler must return a Response -- it cannot raise another exception

Question 3 / 12

What is RequestValidationError and how do you customize its response?

RequestValidationError is raised automatically when FastAPI (via Pydantic) cannot validate the incoming request data -- path parameters, query parameters, headers, or the request body.

Default behavior:

FastAPI returns a 422 Unprocessable Entity with a detailed error response showing exactly which fields failed and why:

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "name"],
      "msg": "Field required",
      "input": {},
      "url": "..."
    }
  ]
}

When it is raised:

Missing required fields in the request body
Wrong data types (string where int expected)
Failed Pydantic validators (min_length, ge, regex, etc.)
Invalid path parameters (e.g., non-integer for int path param)
Invalid query parameters

Customizing the response:

Override the handler by registering your own for RequestValidationError. This is useful for:

Returning a simpler error format for frontend consumption
Translating technical Pydantic errors into user-friendly messages
Logging validation errors for debugging
Matching your API's standard error format

Accessing error details:

exc.errors() returns the list of validation errors
exc.body returns the raw request body that failed validation
Each error has loc (location), msg (message), type (error type), and input (the value received)

Pseudo Code

from fastapi.exceptions import RequestValidationError

@app.exception_handler(RequestValidationError)
async def validation_handler(request, exc):
    errors = []
    for error in exc.errors():
        field = ".".join(str(loc) for loc in error["loc"])
        errors.append({"field": field, "message": error["msg"]})
    return JSONResponse(status_code=422, content={"errors": errors})

Code

from fastapi import FastAPI, Request
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from fastapi.testclient import TestClient
from pydantic import BaseModel, Field

app = FastAPI()

# --- Custom validation error handler ---
@app.exception_handler(RequestValidationError)
async def custom_validation_handler(request: Request, exc: RequestValidationError):
    """Transform Pydantic errors into a simpler format."""
    errors = []
    for error in exc.errors():
        # loc is a tuple like ("body", "name") or ("query", "page")
        location = ".".join(str(part) for part in error["loc"])
        errors.append({
            "field": location,
            "message": error["msg"],
            "type": error["type"],
        })
    return JSONResponse(
        status_code=422,
        content={
            "error": "validation_failed",
            "message": f"{len(errors)} validation error(s)",
            "details": errors,
        },
    )

class CreateUser(BaseModel):
    name: str = Field(min_length=2, max_length=50)
    email: str
    age: int = Field(ge=18, le=120)

@app.post("/users")
def create_user(user: CreateUser):
    return {"created": user.name}

@app.get("/items/{item_id}")
def get_item(item_id: int, page: int = 1):
    return {"item_id": item_id, "page": page}

# --- Test ---
client = TestClient(app)

# Missing required fields
resp = client.post("/users", json={})
print(f"Status: {resp.status_code}")
data = resp.json()
print(f"Error: {data['error']}")
print(f"Count: {data['message']}")
for err in data["details"]:
    print(f"  {err['field']}: {err['message']}")

# Invalid types
resp = client.post("/users", json={"name": "A", "email": "test@test.com", "age": 10})
print(f"\nAge too low: {resp.json()['details'][0]['message']}")

# Invalid path param
resp = client.get("/items/not-a-number")
print(f"Bad path: {resp.json()['details'][0]['field']}")

Status: 422
Error: validation_failed
Count: 3 validation error(s)
body.name: Field required
body.email: Field required
body.age: Field required

Age too low: Input should be greater than or equal to 18
Bad path: path.item_id

Key Points

•RequestValidationError is raised automatically when request data fails Pydantic validation
•Override with @app.exception_handler(RequestValidationError) to customize the 422 response
•exc.errors() returns a list of dicts with loc, msg, type, and input fields
•exc.body contains the raw request body that failed validation

Gotchas

•Import RequestValidationError from fastapi.exceptions, not from pydantic
•The loc tuple includes the source -- ('body', 'field'), ('query', 'param'), ('path', 'param') -- so you know where the error occurred
•Overriding the handler replaces ALL validation error responses -- ensure your format covers all cases

RequestValidationError is raised when request data fails Pydantic validation (wrong types, missing fields, constraint violations). Override its handler with @app.exception_handler(RequestValidationError) to return a custom error format. Access errors via exc.errors() and the raw body via exc.body.

•exc.errors() returns structured validation error details with loc and msg

from fastapi import FastAPI, Request
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse

app = FastAPI()

@app.exception_handler(RequestValidationError)
async def validation_handler(request: Request, exc: RequestValidationError):
    errors = [{"field": ".".join(str(l) for l in e["loc"]), "msg": e["msg"]} for e in exc.errors()]
    return JSONResponse(status_code=422, content={"errors": errors})

Import from fastapi.exceptions, not from pydantic

Question 4 / 12

What is the difference between FastAPI's HTTPException and Starlette's HTTPException?

FastAPI has its own HTTPException that extends Starlette's. They look similar but behave differently, and mixing them up causes subtle bugs.

Key differences:

Feature	Starlette HTTPException	FastAPI HTTPException
Import	`from starlette.exceptions import HTTPException`	`from fastapi import HTTPException`
`detail` type	`str` only	Any JSON-serializable (str, dict, list)
Default handler	Returns plain text	Returns JSON `{"detail": ...}`
Inheritance	Base class	Subclass of Starlette's HTTPException

Why it matters:

FastAPI's HTTPException accepts detail={"code": "ERR", "fields": [...]} -- Starlette's does not
If you override @app.exception_handler(StarletteHTTPException), it catches both FastAPI's and Starlette's since FastAPI's is a subclass
If you override @app.exception_handler(FastAPIHTTPException), it only catches FastAPI's
Third-party middleware (from Starlette ecosystem) raises Starlette's HTTPException, not FastAPI's

Best practice:

Use from fastapi import HTTPException in your endpoints
When overriding the exception handler, import Starlette's to catch all HTTP exceptions:
```
from starlette.exceptions import HTTPException as StarletteHTTPException
```
Register the handler for StarletteHTTPException to catch exceptions from both FastAPI and Starlette middleware

Pseudo Code

from fastapi import HTTPException as FastAPIHTTPException
from starlette.exceptions import HTTPException as StarletteHTTPException

# FastAPI's -- accepts dict detail
raise FastAPIHTTPException(status_code=400, detail={"code": "INVALID"})

# Starlette's -- string detail only
raise StarletteHTTPException(status_code=400, detail="Bad request")

# To catch ALL HTTP exceptions (both FastAPI and Starlette):
@app.exception_handler(StarletteHTTPException)
async def handle_all(request, exc):
    ...

Code

from fastapi import FastAPI, HTTPException as FastAPIHTTPException, Request
from starlette.exceptions import HTTPException as StarletteHTTPException
from fastapi.responses import JSONResponse
from fastapi.testclient import TestClient

app = FastAPI()

# --- Handler for ALL HTTPExceptions (Starlette base catches FastAPI subclass too) ---
@app.exception_handler(StarletteHTTPException)
async def unified_http_exception_handler(
    request: Request, exc: StarletteHTTPException
):
    """Handles both FastAPI and Starlette HTTPExceptions."""
    return JSONResponse(
        status_code=exc.status_code,
        content={
            "error": {
                "status": exc.status_code,
                "detail": exc.detail,
                "type": type(exc).__module__ + "." + type(exc).__name__,
            }
        },
    )

@app.get("/fastapi-error")
def fastapi_error():
    # FastAPI's HTTPException -- dict detail works
    raise FastAPIHTTPException(
        status_code=400,
        detail={"code": "INVALID_INPUT", "field": "email"},
    )

@app.get("/starlette-error")
def starlette_error():
    # Starlette's HTTPException -- string detail only
    raise StarletteHTTPException(
        status_code=400,
        detail="Bad request from Starlette",
    )

# --- Test ---
client = TestClient(app)

# FastAPI exception with dict detail
resp = client.get("/fastapi-error")
print(f"FastAPI: {resp.json()}")

# Starlette exception with string detail
resp = client.get("/starlette-error")
print(f"Starlette: {resp.json()}")

# Check inheritance
print(f"FastAPI is subclass: {issubclass(FastAPIHTTPException, StarletteHTTPException)}")

FastAPI: {'error': {'status': 400, 'detail': {'code': 'INVALID_INPUT', 'field': 'email'}, 'type': 'fastapi.exceptions.HTTPException'}}
Starlette: {'error': {'status': 400, 'detail': 'Bad request from Starlette', 'type': 'starlette.exceptions.HTTPException'}}
FastAPI is subclass: True

Key Points

•FastAPI's HTTPException accepts any JSON-serializable detail (str, dict, list)
•Starlette's HTTPException only accepts string detail
•FastAPI's HTTPException is a subclass of Starlette's -- catching Starlette's catches both
•Third-party Starlette middleware raises Starlette's HTTPException, not FastAPI's

Gotchas

•If you only handle FastAPI's HTTPException, errors from Starlette middleware will use the default plain-text handler
•Passing a dict to Starlette's HTTPException detail will work but get converted to a string representation, not JSON
•When overriding the handler, register for StarletteHTTPException to catch all HTTP errors from both frameworks

FastAPI's HTTPException extends Starlette's and allows detail to be any JSON-serializable type (dict, list), not just strings. To catch all HTTP exceptions (from both FastAPI and Starlette middleware), register your handler for starlette.exceptions.HTTPException since FastAPI's is a subclass.

•FastAPI's HTTPException is a subclass of Starlette's with richer detail support

from fastapi import HTTPException  # Accepts dict/list detail
from starlette.exceptions import HTTPException as StarletteHTTPException  # String only

# FastAPI's -- structured detail
raise HTTPException(status_code=400, detail={"code": "ERR", "field": "email"})

# Catch ALL HTTP exceptions:
@app.exception_handler(StarletteHTTPException)
async def handle_all(request, exc):
    return JSONResponse(status_code=exc.status_code, content={"error": exc.detail})

Only handling FastAPI's HTTPException misses errors from Starlette middleware

Question 5 / 12

How do you format error responses consistently?

Consistent error formatting means every error response from your API follows the same structure, regardless of whether it is a validation error, an HTTPException, or an unhandled exception.

Why consistency matters:

Frontend developers can write a single error parser
Easier to log, monitor, and alert on errors
Better developer experience for API consumers
Machine-readable error codes enable programmatic handling

Recommended error format:

{
  "error": {
    "code": "ITEM_NOT_FOUND",
    "message": "Item 42 does not exist",
    "details": [],
    "path": "/items/42",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Implementation strategy:

Define an ErrorResponse Pydantic model for the error structure
Create a helper function to build consistent error responses
Override handlers for HTTPException, RequestValidationError, and Exception
Use the same format in all three handlers

Fields to include:

code: Machine-readable error code (e.g., "ITEM_NOT_FOUND", "VALIDATION_FAILED")
message: Human-readable description
details: Additional context (validation errors, field-level issues)
path: The request path that caused the error
timestamp: When the error occurred (ISO 8601)

Pseudo Code

def make_error_response(code, message, status, path, details=None):
    return JSONResponse(
        status_code=status,
        content={
            "error": {
                "code": code,
                "message": message,
                "details": details or [],
                "path": path,
                "timestamp": now_iso(),
            }
        },
    )

# Register for HTTPException, RequestValidationError, and Exception
# All use make_error_response() for consistent format

Code

from datetime import datetime, timezone
from fastapi import FastAPI, Request, HTTPException
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from fastapi.testclient import TestClient
from pydantic import BaseModel, Field
from starlette.exceptions import HTTPException as StarletteHTTPException

app = FastAPI()

# --- Consistent error response builder ---
def error_response(
    status_code: int,
    code: str,
    message: str,
    path: str,
    details: list | None = None,
) -> JSONResponse:
    return JSONResponse(
        status_code=status_code,
        content={
            "error": {
                "code": code,
                "message": message,
                "details": details or [],
                "path": path,
                "timestamp": datetime.now(timezone.utc).isoformat(),
            }
        },
    )

# --- Override all error handlers ---
@app.exception_handler(StarletteHTTPException)
async def http_exception_handler(request: Request, exc: StarletteHTTPException):
    return error_response(
        status_code=exc.status_code,
        code=f"HTTP_{exc.status_code}",
        message=str(exc.detail),
        path=request.url.path,
    )

@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc: RequestValidationError):
    details = [
        {"field": ".".join(str(l) for l in e["loc"]), "message": e["msg"]}
        for e in exc.errors()
    ]
    return error_response(
        status_code=422,
        code="VALIDATION_FAILED",
        message=f"{len(details)} validation error(s)",
        path=request.url.path,
        details=details,
    )

@app.exception_handler(Exception)
async def unhandled_exception_handler(request: Request, exc: Exception):
    return error_response(
        status_code=500,
        code="INTERNAL_ERROR",
        message="An unexpected error occurred",
        path=request.url.path,
    )

class CreateItem(BaseModel):
    name: str = Field(min_length=1)
    price: float = Field(gt=0)

@app.post("/items")
def create_item(item: CreateItem):
    return {"created": item.name}

@app.get("/items/{item_id}")
def get_item(item_id: int):
    raise HTTPException(status_code=404, detail="Item not found")

# --- Test ---
client = TestClient(app, raise_server_exceptions=False)

# HTTP exception -> consistent format
resp = client.get("/items/1")
print(f"HTTP error: {resp.json()['error']['code']}")

# Validation error -> consistent format
resp = client.post("/items", json={"name": "", "price": -5})
err = resp.json()["error"]
print(f"Validation: {err['code']} - {err['message']}")
for d in err["details"]:
    print(f"  {d['field']}: {d['message']}")

# All errors have the same top-level structure
print(f"Both have 'error' key: {True}")

HTTP error: HTTP_404
Validation: VALIDATION_FAILED - 2 validation error(s)
body.name: String should have at least 1 character
body.price: Input should be greater than 0
Both have 'error' key: True

Key Points

•Create a helper function that builds error responses in a consistent format
•Override handlers for HTTPException, RequestValidationError, and Exception
•Include machine-readable codes, human-readable messages, and contextual details
•Always include the request path and timestamp for debugging and logging

Gotchas

•The Exception handler catches truly unhandled errors -- never expose stack traces or internal details to clients
•Register the handler for StarletteHTTPException (not FastAPI's) to catch errors from Starlette middleware too
•The Exception handler requires raise_server_exceptions=False in TestClient to test properly

Create a helper function that returns JSONResponse with a consistent structure (code, message, details, path, timestamp). Override handlers for HTTPException, RequestValidationError, and Exception -- all three use the same helper for uniform output.

•One helper function ensures every error has the same JSON structure

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

app = FastAPI()

def error_response(status: int, code: str, message: str, path: str):
    return JSONResponse(status_code=status, content={"error": {"code": code, "message": message, "path": path}})

@app.exception_handler(StarletteHTTPException)
async def http_handler(request: Request, exc):
    return error_response(exc.status_code, f"HTTP_{exc.status_code}", str(exc.detail), request.url.path)

@app.exception_handler(RequestValidationError)
async def validation_handler(request: Request, exc):
    return error_response(422, "VALIDATION_FAILED", "Invalid input", request.url.path)

Never expose internal error details (stack traces, file paths) in the Exception handler

Question 6 / 12

How do you add logging to exception handlers?

Adding logging to exception handlers is essential for debugging production issues. You want to log error details server-side while returning a clean, safe response to the client.

What to log:

Request method and path
Exception type and message
Full traceback (for unhandled exceptions)
Request body (for validation errors, sanitized)
Client IP and user agent
Request ID (for correlation with other logs)

Log levels:

logger.warning(): For expected errors (404, 422) -- these are not bugs
logger.error(): For unexpected errors (500) -- these need investigation
logger.exception(): Same as error but automatically includes the traceback

Security considerations:

Never log passwords, tokens, or sensitive headers
Sanitize request bodies before logging
Do not expose internal details (stack traces, file paths) to the client
Log the full traceback server-side but return a generic message to the client

Structured logging:

For production, use structured logging (JSON) with libraries like structlog or python-json-logger for easy parsing by log aggregators (ELK, Datadog, CloudWatch).

Pseudo Code

@app.exception_handler(Exception)
async def handle_unhandled(request, exc):
    logger.exception(
        "Unhandled error",
        extra={
            "path": request.url.path,
            "method": request.method,
            "error": str(exc),
        }
    )
    return JSONResponse(status_code=500, content={"error": "Internal error"})

Code

import logging
import traceback
from fastapi import FastAPI, Request, HTTPException
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from fastapi.testclient import TestClient
from pydantic import BaseModel, Field

# Configure logging
logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
logger = logging.getLogger("api.errors")

app = FastAPI()

@app.exception_handler(HTTPException)
async def http_exception_with_logging(request: Request, exc: HTTPException):
    """Log HTTP exceptions at WARNING level."""
    logger.warning(
        f"HTTP {exc.status_code} on {request.method} {request.url.path}: {exc.detail}"
    )
    return JSONResponse(
        status_code=exc.status_code,
        content={"error": {"code": f"HTTP_{exc.status_code}", "message": str(exc.detail)}},
    )

@app.exception_handler(RequestValidationError)
async def validation_error_with_logging(request: Request, exc: RequestValidationError):
    """Log validation errors at WARNING level."""
    error_count = len(exc.errors())
    fields = [".".join(str(l) for l in e["loc"]) for e in exc.errors()]
    logger.warning(
        f"Validation failed on {request.method} {request.url.path}: "
        f"{error_count} error(s) in fields: {', '.join(fields)}"
    )
    return JSONResponse(
        status_code=422,
        content={"error": {"code": "VALIDATION_FAILED", "message": f"{error_count} error(s)"}},
    )

@app.exception_handler(Exception)
async def unhandled_exception_with_logging(request: Request, exc: Exception):
    """Log unhandled exceptions at ERROR level with traceback."""
    logger.error(
        f"Unhandled {type(exc).__name__} on {request.method} {request.url.path}: {exc}"
    )
    logger.error(f"Traceback:\n{traceback.format_exc()}")
    # Never expose internal details to the client
    return JSONResponse(
        status_code=500,
        content={"error": {"code": "INTERNAL_ERROR", "message": "An unexpected error occurred"}},
    )

class CreateUser(BaseModel):
    name: str = Field(min_length=1)

@app.post("/users")
def create_user(user: CreateUser):
    return {"name": user.name}

@app.get("/items/{item_id}")
def get_item(item_id: int):
    raise HTTPException(status_code=404, detail="Item not found")

@app.get("/crash")
def crash():
    raise RuntimeError("Something broke")

# --- Test ---
client = TestClient(app, raise_server_exceptions=False)

# HTTP exception -> WARNING log
resp = client.get("/items/1")
print(f"404 response: {resp.json()['error']['code']}")

# Validation error -> WARNING log
resp = client.post("/users", json={"name": ""})
print(f"422 response: {resp.json()['error']['code']}")

# Unhandled exception -> ERROR log with traceback
resp = client.get("/crash")
print(f"500 response: {resp.json()['error']['message']}")

WARNING: HTTP 404 on GET /items/1: Item not found
404 response: HTTP_404
WARNING: Validation failed on POST /users: 1 error(s) in fields: body.name
422 response: VALIDATION_FAILED
ERROR: Unhandled RuntimeError on GET /crash: Something broke
ERROR: Traceback:
...
500 response: An unexpected error occurred

Key Points

•Use logger.warning() for expected errors (404, 422) and logger.error() for unexpected ones (500)
•logger.exception() automatically includes the traceback -- use it instead of manually formatting
•Log full error details server-side but return safe, generic messages to the client
•Include request method, path, and error type in log messages for easy debugging

Gotchas

•Never log sensitive data (passwords, auth tokens, PII) -- sanitize request bodies before logging
•The Exception handler in TestClient requires raise_server_exceptions=False to avoid re-raising in tests
•logging.exception() must be called inside an except block -- otherwise it logs 'NoneType: None' for the traceback

Add logger.warning() in HTTP/validation handlers and logger.error() (with traceback) in the unhandled exception handler. Log method, path, and error details server-side. Return clean, safe error messages to the client -- never expose stack traces.

•logger.exception() logs the error message plus the full traceback automatically

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

logger = logging.getLogger("api")
app = FastAPI()

@app.exception_handler(Exception)
async def log_unhandled(request: Request, exc: Exception):
    logger.exception(f"Unhandled error on {request.method} {request.url.path}")
    return JSONResponse(status_code=500, content={"error": "Internal error"})

Never expose stack traces or internal paths to the client in the error response

Question 7 / 12

How do you handle 404 errors for missing resources?

Handling 404 errors properly is fundamental to good API design. There are two types of 404s in FastAPI:

1. Route not found (no matching endpoint):

FastAPI/Starlette returns a default {"detail": "Not Found"} response
Customize by overriding the HTTPException handler

2. Resource not found (endpoint exists, item does not):

You raise HTTPException(status_code=404) in your endpoint
This is the more common case in CRUD APIs

Patterns for resource lookups:

Pattern A: Direct raise in endpoint

if item_id not in db:
    raise HTTPException(404, detail="Item not found")

Pattern B: Dependency that raises

def get_item_or_404(item_id: int) -> Item:
    item = db.get(item_id)
    if not item:
        raise HTTPException(404)
    return item

Pattern C: Custom exception class

class NotFoundError(Exception): ...

Best practices:

Include the resource type and ID in the error message
Use dependencies for reusable lookup-or-404 logic
Return consistent error format across all 404s
Consider returning helpful information (e.g., "Did you mean...?") for search-like endpoints

Pseudo Code

# Dependency pattern (most reusable)
def get_item_or_404(item_id: int, db = Depends(get_db)) -> Item:
    item = db.query(Item).get(item_id)
    if not item:
        raise HTTPException(404, detail=f"Item {item_id} not found")
    return item

@app.get("/items/{item_id}")
def read_item(item: Annotated[Item, Depends(get_item_or_404)]):
    return item

@app.put("/items/{item_id}")
def update_item(item: Annotated[Item, Depends(get_item_or_404)], data: UpdateData):
    ...

Code

from typing import Annotated
from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.testclient import TestClient
from pydantic import BaseModel

app = FastAPI()

# Simulated database
class Item(BaseModel):
    id: int
    name: str
    price: float

ITEMS_DB: dict[int, Item] = {
    1: Item(id=1, name="Widget", price=9.99),
    2: Item(id=2, name="Gadget", price=24.99),
}

# --- Reusable dependency for lookup-or-404 ---
def get_item_or_404(item_id: int) -> Item:
    """Reusable dependency: returns item or raises 404."""
    item = ITEMS_DB.get(item_id)
    if item is None:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail={
                "error": "not_found",
                "resource": "item",
                "id": item_id,
                "message": f"Item {item_id} does not exist",
            },
        )
    return item

FoundItem = Annotated[Item, Depends(get_item_or_404)]

# Same dependency used across multiple endpoints
@app.get("/items/{item_id}")
def read_item(item: FoundItem):
    return item

@app.put("/items/{item_id}")
def update_item(item: FoundItem, name: str = "Updated"):
    item.name = name
    return item

@app.delete("/items/{item_id}")
def delete_item(item: FoundItem):
    del ITEMS_DB[item.id]
    return {"deleted": item.id}

# --- Test ---
client = TestClient(app)

# Existing item
resp = client.get("/items/1")
print(f"Found: {resp.json()['name']}")

# Missing item -> 404 with structured detail
resp = client.get("/items/999")
print(f"Status: {resp.status_code}")
print(f"Error: {resp.json()['detail']}")

# Same 404 logic works for PUT and DELETE
resp = client.put("/items/999")
print(f"PUT 404: {resp.status_code}")
resp = client.delete("/items/999")
print(f"DELETE 404: {resp.status_code}")

Found: Widget
Status: 404
Error: {'error': 'not_found', 'resource': 'item', 'id': 999, 'message': 'Item 999 does not exist'}
PUT 404: 404
DELETE 404: 404

Key Points

•Use a dependency (get_item_or_404) to DRY up lookup-or-raise logic across endpoints
•Annotated[Item, Depends(get_item_or_404)] creates a reusable type alias
•Include resource type and ID in the error detail for easier debugging
•The same dependency works for GET, PUT, DELETE -- any endpoint that needs the item

Gotchas

•A dependency that raises 404 prevents the endpoint from running at all -- the error is returned before the endpoint body executes
•Default 404s for unmatched routes have no detail beyond 'Not Found' -- override the HTTPException handler to customize those
•Returning 404 for collection endpoints (e.g., /items?category=xyz with no results) is wrong -- return an empty list with 200 instead

Create a reusable dependency that looks up a resource and raises HTTPException(status_code=404) if not found. Use Annotated[Item, Depends(get_item_or_404)] to share the same lookup logic across GET, PUT, and DELETE endpoints.

•Dependency pattern DRYs up 404 logic across all CRUD endpoints

from typing import Annotated
from fastapi import FastAPI, Depends, HTTPException

app = FastAPI()

def get_item_or_404(item_id: int):
    item = db.get(item_id)
    if not item:
        raise HTTPException(status_code=404, detail=f"Item {item_id} not found")
    return item

@app.get("/items/{item_id}")
def read(item: Annotated[dict, Depends(get_item_or_404)]):
    return item

Empty list results should return 200 with [], not 404

Question 8 / 12

How do you create custom exception classes?

Custom exception classes let you define domain-specific errors that carry structured data and map to specific HTTP responses. This separates business logic from HTTP concerns.

Why custom exceptions:

Clarity: raise InsufficientFundsError(balance=50, required=100) is clearer than raise HTTPException(400, detail="...")
Separation: Business logic does not need to know about HTTP status codes
Structured data: Each exception carries relevant context as attributes
Centralized handling: One handler converts exceptions to responses
Testability: You can catch and assert on specific exception types in unit tests

Design pattern:

Create a base AppException with common fields (code, message, status_code)
Create specific subclasses for each error domain
Register a single handler for the base class that catches all subclasses
Each subclass sets sensible defaults for code and status_code

Hierarchy example:

AppException (base)
├── NotFoundError (404)
│   ├── UserNotFoundError
│   └── ItemNotFoundError
├── ConflictError (409)
│   ├── DuplicateEmailError
│   └── DuplicateUsernameError
└── AuthorizationError (403)
    └── InsufficientPermissionsError

Pseudo Code

class AppException(Exception):
    code: str
    message: str
    status_code: int

class NotFoundError(AppException):
    status_code = 404

class UserNotFoundError(NotFoundError):
    code = "USER_NOT_FOUND"
    def __init__(self, user_id):
        super().__init__(message=f"User {user_id} not found")

@app.exception_handler(AppException)
async def handle(request, exc):
    return JSONResponse(status_code=exc.status_code, ...)

Code

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
from fastapi.testclient import TestClient

app = FastAPI()

# --- Exception hierarchy ---
class AppException(Exception):
    """Base exception for all application errors."""
    def __init__(self, code: str, message: str, status_code: int = 400, details: dict | None = None):
        self.code = code
        self.message = message
        self.status_code = status_code
        self.details = details or {}
        super().__init__(message)

class NotFoundError(AppException):
    def __init__(self, resource: str, resource_id: int | str):
        super().__init__(
            code=f"{resource.upper()}_NOT_FOUND",
            message=f"{resource.capitalize()} '{resource_id}' does not exist",
            status_code=404,
            details={"resource": resource, "id": resource_id},
        )

class ConflictError(AppException):
    def __init__(self, resource: str, field: str, value: str):
        super().__init__(
            code=f"DUPLICATE_{field.upper()}",
            message=f"{resource.capitalize()} with {field}='{value}' already exists",
            status_code=409,
            details={"field": field, "value": value},
        )

class BusinessRuleError(AppException):
    def __init__(self, code: str, message: str, details: dict | None = None):
        super().__init__(code=code, message=message, status_code=422, details=details)

# --- Single handler for all AppExceptions ---
@app.exception_handler(AppException)
async def app_exception_handler(request: Request, exc: AppException):
    return JSONResponse(
        status_code=exc.status_code,
        content={
            "error": {
                "code": exc.code,
                "message": exc.message,
                "details": exc.details,
            }
        },
    )

# --- Usage in endpoints ---
USERS = {"alice@example.com": {"id": 1, "name": "Alice", "email": "alice@example.com"}}

@app.get("/users/{user_id}")
def get_user(user_id: int):
    raise NotFoundError(resource="user", resource_id=user_id)

@app.post("/users")
def create_user(email: str = "alice@example.com"):
    if email in USERS:
        raise ConflictError(resource="user", field="email", value=email)
    return {"created": email}

@app.post("/transfer")
def transfer(amount: float = 100, balance: float = 50):
    if amount > balance:
        raise BusinessRuleError(
            code="INSUFFICIENT_FUNDS",
            message=f"Cannot transfer ${amount}: only ${balance} available",
            details={"required": amount, "available": balance},
        )
    return {"transferred": amount}

# --- Test ---
client = TestClient(app)

# Not found
resp = client.get("/users/42")
print(f"404: {resp.json()['error']['code']} - {resp.json()['error']['message']}")

# Conflict
resp = client.post("/users?email=alice@example.com")
print(f"409: {resp.json()['error']['code']}")

# Business rule
resp = client.post("/transfer?amount=100&balance=50")
err = resp.json()["error"]
print(f"422: {err['code']} - {err['details']}")

404: USER_NOT_FOUND - User '42' does not exist
409: DUPLICATE_EMAIL
422: INSUFFICIENT_FUNDS - {'required': 100.0, 'available': 50.0}

Key Points

•Create a base AppException with code, message, status_code, and details fields
•Subclasses set sensible defaults -- NotFoundError always uses 404, ConflictError uses 409
•A single handler for the base class catches all subclasses automatically
•Custom exceptions separate business logic from HTTP concerns

Gotchas

•Always call super().__init__() in your exception classes or Python's traceback display may break
•A handler registered for a base class catches subclasses -- but a more specific handler registered separately takes priority
•Custom exceptions are not the same as HTTPException -- they need their own registered handler

Create a base AppException(code, message, status_code) class, then subclass it for specific errors (NotFoundError, ConflictError). Register one handler with @app.exception_handler(AppException) that catches all subclasses and returns a consistent JSON response.

•One handler for the base class catches all subclass exceptions

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

app = FastAPI()

class AppException(Exception):
    def __init__(self, code: str, message: str, status_code: int = 400):
        self.code = code
        self.message = message
        self.status_code = status_code

class NotFoundError(AppException):
    def __init__(self, resource: str, id: int):
        super().__init__(f"{resource.upper()}_NOT_FOUND", f"{resource} {id} not found", 404)

@app.exception_handler(AppException)
async def handler(request: Request, exc: AppException):
    return JSONResponse(status_code=exc.status_code, content={"error": {"code": exc.code, "message": exc.message}})

Custom exceptions need their own handler -- they are not caught by the HTTPException handler

Question 9 / 12

How do you handle database errors in FastAPI?

Database errors in FastAPI need special handling because they are infrastructure errors that should be translated into meaningful HTTP responses.

Common database errors:

SQLAlchemy Exception	Meaning	HTTP Status
`IntegrityError`	Unique constraint / foreign key violation	409 Conflict
`NoResultFound`	Query expected a result, got none	404 Not Found
`OperationalError`	Connection failure, timeout	503 Service Unavailable
`DataError`	Invalid data (overflow, bad format)	400 Bad Request

Strategy:

Catch specific exceptions in dependencies or service functions
Translate them to domain exceptions or HTTPExceptions
Never expose raw database errors to clients (they may contain SQL, table names, etc.)
Log the full error server-side for debugging
Roll back the session on error to avoid corrupted state

Approaches:

Approach A: Handle in each endpoint (simple, less reusable) Approach B: Handle in a dependency (reusable session management) Approach C: Global exception handler (catches anything missed)

SQLAlchemy session management:

Use a dependency with yield to automatically handle commit/rollback:

If the endpoint succeeds, the session is committed (or you commit explicitly)
If an exception occurs, the session is rolled back in the finally block

Pseudo Code

def get_db():
    db = SessionLocal()
    try:
        yield db
    except IntegrityError:
        db.rollback()
        raise HTTPException(409, "Duplicate entry")
    finally:
        db.close()

@app.exception_handler(OperationalError)
async def db_connection_handler(request, exc):
    logger.error(f"Database connection error: {exc}")
    return JSONResponse(503, {"error": "Service temporarily unavailable"})

Code

import logging
from fastapi import FastAPI, Depends, HTTPException, Request, status
from fastapi.responses import JSONResponse
from fastapi.testclient import TestClient
from sqlalchemy import create_engine, Column, Integer, String
from sqlalchemy.orm import sessionmaker, Session, DeclarativeBase
from sqlalchemy.exc import IntegrityError, OperationalError

logger = logging.getLogger("api.db")

# --- Database setup ---
engine = create_engine("sqlite:///:memory:")
SessionLocal = sessionmaker(bind=engine)

class Base(DeclarativeBase):
    pass

class User(Base):
    __tablename__ = "users"
    id = Column(Integer, primary_key=True)
    email = Column(String, unique=True, nullable=False)
    name = Column(String, nullable=False)

Base.metadata.create_all(engine)

app = FastAPI()

# --- DB dependency with error handling ---
def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

# --- Global handler for IntegrityError ---
@app.exception_handler(IntegrityError)
async def integrity_error_handler(request: Request, exc: IntegrityError):
    logger.warning(f"Integrity error on {request.url.path}: {exc.orig}")
    return JSONResponse(
        status_code=status.HTTP_409_CONFLICT,
        content={"error": {"code": "DUPLICATE_ENTRY", "message": "Resource already exists"}},
    )

@app.post("/users")
def create_user(name: str, email: str, db: Session = Depends(get_db)):
    user = User(name=name, email=email)
    db.add(user)
    try:
        db.commit()
    except IntegrityError:
        db.rollback()
        raise HTTPException(
            status_code=status.HTTP_409_CONFLICT,
            detail={"code": "DUPLICATE_EMAIL", "message": f"Email '{email}' already exists"},
        )
    db.refresh(user)
    return {"id": user.id, "name": user.name, "email": user.email}

@app.get("/users/{user_id}")
def get_user(user_id: int, db: Session = Depends(get_db)):
    user = db.query(User).filter(User.id == user_id).first()
    if not user:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail=f"User {user_id} not found",
        )
    return {"id": user.id, "name": user.name, "email": user.email}

# --- Test ---
client = TestClient(app)

# Create user
resp = client.post("/users?name=Alice&email=alice@test.com")
print(f"Created: {resp.json()}")

# Duplicate email -> 409
resp = client.post("/users?name=Bob&email=alice@test.com")
print(f"Duplicate: {resp.status_code} {resp.json()['detail']}")

# Not found -> 404
resp = client.get("/users/999")
print(f"Not found: {resp.status_code}")

Created: {'id': 1, 'name': 'Alice', 'email': 'alice@test.com'}
Duplicate: 409 {'code': 'DUPLICATE_EMAIL', 'message': "Email 'alice@test.com' already exists"}
Not found: 404

Key Points

•Catch IntegrityError (unique/FK violations) and translate to 409 Conflict
•Always rollback the session after a database error before raising HTTPException
•Use a yield dependency for automatic session cleanup in the finally block
•Never expose raw database error messages to clients -- they may contain SQL and table names

Gotchas

•You must call db.rollback() after an IntegrityError before the session can be reused
•SQLAlchemy's IntegrityError wraps the DB driver's error in .orig -- log that for debugging
•OperationalError (connection issues) should return 503 Service Unavailable, not 500
•Using db.commit() inside the endpoint gives you fine-grained control vs auto-commit in the dependency

Catch IntegrityError (unique violations) and translate to 409 Conflict. Always call db.rollback() before raising. Use a yield dependency for session cleanup. Never expose raw SQL errors to clients.

•Catch IntegrityError, rollback, then raise HTTPException with 409

from fastapi import FastAPI, Depends, HTTPException
from sqlalchemy.exc import IntegrityError
from sqlalchemy.orm import Session

app = FastAPI()

@app.post("/users")
def create_user(name: str, email: str, db: Session = Depends(get_db)):
    user = User(name=name, email=email)
    db.add(user)
    try:
        db.commit()
    except IntegrityError:
        db.rollback()
        raise HTTPException(status_code=409, detail="Email already exists")
    return {"id": user.id}

Must rollback after IntegrityError before the session can be used again

Question 10 / 12

How do you return different error formats (JSON vs HTML)?

Content negotiation for errors lets your API return JSON for API clients and HTML for browsers, based on the Accept header.

How it works:

Check the Accept header in the request
If it contains text/html, return an HTML error page
If it contains application/json (or anything else), return JSON
Implement this in your exception handlers

The Accept header:

Browsers send: Accept: text/html,application/xhtml+xml,...
API clients send: Accept: application/json
curl sends: Accept: */*

When to use this:

APIs that also serve web pages (e.g., documentation, admin panels)
FastAPI apps that combine API endpoints with Jinja2 template endpoints
Public APIs where users might navigate to endpoints in a browser

Implementation:

Create a helper that checks the Accept header and returns the appropriate response type. Use this in all your exception handlers.

Pseudo Code

def error_response(request, status_code, code, message):
    accept = request.headers.get("accept", "")
    if "text/html" in accept:
        return HTMLResponse(render_error_page(status_code, message))
    return JSONResponse(status_code, {"error": {"code": code, "message": message}})

Code

from fastapi import FastAPI, HTTPException, Request
from fastapi.responses import JSONResponse, HTMLResponse
from starlette.exceptions import HTTPException as StarletteHTTPException
from fastapi.testclient import TestClient

app = FastAPI()

def make_error_response(
    request: Request,
    status_code: int,
    code: str,
    message: str,
) -> JSONResponse | HTMLResponse:
    """Return JSON or HTML based on Accept header."""
    accept = request.headers.get("accept", "")
    
    if "text/html" in accept:
        html = f"""<!DOCTYPE html>
<html>
<head><title>Error {status_code}</title></head>
<body>
  <h1>{status_code} - {code}</h1>
  <p>{message}</p>
</body>
</html>"""
        return HTMLResponse(content=html, status_code=status_code)
    
    return JSONResponse(
        status_code=status_code,
        content={"error": {"code": code, "message": message}},
    )

@app.exception_handler(StarletteHTTPException)
async def http_exception_handler(request: Request, exc: StarletteHTTPException):
    return make_error_response(
        request,
        status_code=exc.status_code,
        code=f"HTTP_{exc.status_code}",
        message=str(exc.detail),
    )

@app.get("/items/{item_id}")
def get_item(item_id: int):
    raise HTTPException(status_code=404, detail="Item not found")

# --- Test ---
client = TestClient(app)

# API client -> JSON
resp = client.get("/items/42", headers={"Accept": "application/json"})
print(f"JSON response: {resp.headers['content-type']}")
print(f"Body: {resp.json()}")

# Browser -> HTML
resp = client.get("/items/42", headers={"Accept": "text/html,application/xhtml+xml"})
print(f"HTML response: {resp.headers['content-type']}")
print(f"Contains <h1>: {'<h1>' in resp.text}")

# No Accept header -> JSON (default)
resp = client.get("/items/42")
print(f"Default: {resp.headers['content-type']}")

JSON response: application/json
Body: {'error': {'code': 'HTTP_404', 'message': 'Item not found'}}
HTML response: text/html; charset=utf-8
Contains <h1>: True
Default: application/json

Key Points

•Check request.headers.get('accept') to determine the response format
•Return HTMLResponse for browsers (text/html) and JSONResponse for API clients
•Use a shared helper function so all exception handlers use the same logic
•Default to JSON when no Accept header is present

Gotchas

•The Accept header can contain multiple types with quality factors (e.g., 'text/html;q=0.9') -- a simple 'in' check works for most cases but is not fully spec-compliant
•HTMLResponse sets Content-Type to text/html automatically -- do not set it manually
•Ensure HTML error pages are properly escaped to prevent XSS if error messages contain user input

Check the Accept header in your exception handler: return HTMLResponse for text/html (browsers) and JSONResponse for everything else (API clients). Use a shared helper so all error handlers support both formats.

•Check Accept header to decide between HTMLResponse and JSONResponse

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

app = FastAPI()

def error_response(request: Request, status: int, message: str):
    if "text/html" in request.headers.get("accept", ""):
        return HTMLResponse(f"<h1>{status}</h1><p>{message}</p>", status_code=status)
    return JSONResponse(status_code=status, content={"error": message})

Escape user input in HTML error messages to prevent XSS attacks

Question 11 / 12

How do you handle validation errors for nested models?

Nested model validation in FastAPI automatically validates all levels of nested Pydantic models. When validation fails on a nested field, the loc (location) tuple includes the full path to the failing field.

How nested validation works:

FastAPI deserializes the JSON body into your Pydantic model
Pydantic validates every field recursively through all nested models
If any field at any nesting level fails, a RequestValidationError is raised
The loc field shows the full path: ("body", "address", "zip_code")

Error location format:

The loc tuple uses indices for lists and field names for objects:

("body", "name") -- top-level field
("body", "address", "city") -- nested object field
("body", "items", 2, "price") -- third item in a list, price field

Customizing nested error messages:

Override RequestValidationError to flatten the loc path into a human-readable field name like address.city or items[2].price.

Pydantic v2 error format:

Pydantic v2 errors include type, loc, msg, input (the value that failed), and url (link to docs for that error type).

Pseudo Code

class Address(BaseModel):
    city: str
    zip_code: str = Field(pattern=r"^\d{5}$")

class Order(BaseModel):
    customer: str
    address: Address
    items: list[OrderItem]

# Error loc for nested failure:
# ("body", "address", "zip_code") -> "address.zip_code"
# ("body", "items", 0, "quantity") -> "items[0].quantity"

Code

from fastapi import FastAPI, Request
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from fastapi.testclient import TestClient
from pydantic import BaseModel, Field

app = FastAPI()

# --- Nested models ---
class Address(BaseModel):
    street: str = Field(min_length=1)
    city: str = Field(min_length=1)
    zip_code: str = Field(pattern=r"^\d{5}$")

class OrderItem(BaseModel):
    name: str = Field(min_length=1)
    quantity: int = Field(gt=0)
    price: float = Field(gt=0)

class CreateOrder(BaseModel):
    customer_name: str = Field(min_length=2)
    shipping_address: Address
    items: list[OrderItem] = Field(min_length=1)

# --- Custom handler for readable nested error paths ---
@app.exception_handler(RequestValidationError)
async def nested_validation_handler(request: Request, exc: RequestValidationError):
    errors = []
    for error in exc.errors():
        # Build a readable path from the loc tuple
        parts = []
        for loc in error["loc"]:
            if isinstance(loc, int):
                # List index -> items[0]
                parts[-1] = f"{parts[-1]}[{loc}]"
            else:
                parts.append(str(loc))
        # Skip the first element ("body") for cleaner paths
        field_path = ".".join(parts[1:]) if len(parts) > 1 else parts[0]
        errors.append({
            "field": field_path,
            "message": error["msg"],
            "input": error.get("input"),
        })
    return JSONResponse(
        status_code=422,
        content={
            "error": "validation_failed",
            "count": len(errors),
            "details": errors,
        },
    )

@app.post("/orders")
def create_order(order: CreateOrder):
    return {"status": "created", "items": len(order.items)}

# --- Test ---
client = TestClient(app)

# Multiple nested errors
resp = client.post("/orders", json={
    "customer_name": "A",
    "shipping_address": {
        "street": "123 Main St",
        "city": "",
        "zip_code": "bad",
    },
    "items": [
        {"name": "Widget", "quantity": 2, "price": 9.99},
        {"name": "", "quantity": -1, "price": 0},
    ],
})

data = resp.json()
print(f"Errors: {data['count']}")
for err in data["details"]:
    print(f"  {err['field']}: {err['message']}")

Errors: 6
customer_name: String should have at least 2 characters
shipping_address.city: String should have at least 1 character
shipping_address.zip_code: String should match pattern '^\d{5}$'
items[1].name: String should have at least 1 character
items[1].quantity: Input should be greater than 0
items[1].price: Input should be greater than 0

Key Points

•Pydantic validates all nesting levels recursively -- nested fields are checked automatically
•The loc tuple shows the full path: ('body', 'address', 'city') or ('body', 'items', 2, 'name')
•Integer values in loc are list indices -- use them to build paths like items[2].name
•Override RequestValidationError to flatten nested paths into readable field names

Gotchas

•The first element of loc is always the source ('body', 'query', 'path') -- skip it for user-facing field names
•List indices in loc are integers, not strings -- check with isinstance(loc, int) when building paths
•All nested errors are collected before returning -- Pydantic does not stop at the first error

Pydantic validates nested models recursively. When a nested field fails, the loc tuple shows the full path: ("body", "address", "city") for objects and ("body", "items", 0, "price") for list items. Override RequestValidationError to format these paths as address.city or items[0].price.

•loc tuple contains the full path through nested models including list indices

from pydantic import BaseModel, Field

class Address(BaseModel):
    city: str = Field(min_length=1)
    zip_code: str = Field(pattern=r"^\d{5}$")

class Order(BaseModel):
    address: Address
    items: list[dict]  # Each item is also validated

# Error for bad zip: loc=("body", "address", "zip_code")
# Error for items[2].price: loc=("body", "items", 2, "price")

List indices in loc are integers -- handle them separately from string field names when building paths

Question 12 / 12

How do you implement global error handling for unhandled exceptions?

Global error handling catches any unhandled exception that slips through your other handlers, preventing raw 500 Internal Server Error responses with stack traces from reaching clients.

Why you need it:

Prevents stack traces from leaking to clients (security risk)
Ensures all errors follow your consistent format
Provides a safety net for unexpected bugs
Enables centralized logging and alerting

Implementation:

Register an exception handler for the base Exception class. This catches everything not handled by more specific handlers.

Handler priority:

Specific exception handlers (e.g., IntegrityError, NotFoundError) -- checked first
HTTPException handler -- catches FastAPI/Starlette HTTP exceptions
RequestValidationError handler -- catches validation failures
Exception handler (the global catch-all) -- last resort

Production considerations:

Log everything: traceback, request details, headers (sanitized)
Alert: send to error tracking (Sentry, Datadog, etc.)
Return nothing sensitive: generic message, request ID for support
Include request ID: so support can correlate client reports with server logs

Testing:

TestClient re-raises server exceptions by default. Pass raise_server_exceptions=False to test your 500 handler.

Pseudo Code

# Global catch-all handler
@app.exception_handler(Exception)
async def catch_all(request, exc):
    request_id = generate_id()
    
    # Log full details server-side
    logger.exception(f"[{request_id}] Unhandled {type(exc).__name__}")
    
    # Send to error tracker
    sentry_sdk.capture_exception(exc)
    
    # Return safe response with request ID
    return JSONResponse(
        status_code=500,
        content={"error": "Internal error", "request_id": request_id},
    )

Code

import logging
import uuid
from fastapi import FastAPI, Request, HTTPException
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from fastapi.testclient import TestClient
from starlette.exceptions import HTTPException as StarletteHTTPException

logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
logger = logging.getLogger("api")

app = FastAPI()

# --- Specific handlers first ---
@app.exception_handler(StarletteHTTPException)
async def http_exception_handler(request: Request, exc: StarletteHTTPException):
    return JSONResponse(
        status_code=exc.status_code,
        content={"error": {"code": f"HTTP_{exc.status_code}", "message": str(exc.detail)}},
    )

@app.exception_handler(RequestValidationError)
async def validation_handler(request: Request, exc: RequestValidationError):
    return JSONResponse(
        status_code=422,
        content={"error": {"code": "VALIDATION_FAILED", "message": "Invalid request data"}},
    )

# --- Global catch-all (runs LAST, only for unhandled exceptions) ---
@app.exception_handler(Exception)
async def global_exception_handler(request: Request, exc: Exception):
    request_id = str(uuid.uuid4())[:8]
    
    # Full details logged server-side
    logger.error(
        f"[{request_id}] Unhandled {type(exc).__name__} "
        f"on {request.method} {request.url.path}: {exc}"
    )
    
    # Safe response to client -- no internal details
    return JSONResponse(
        status_code=500,
        content={
            "error": {
                "code": "INTERNAL_ERROR",
                "message": "An unexpected error occurred. Please try again later.",
                "request_id": request_id,
            }
        },
    )

# --- Endpoints ---
@app.get("/ok")
def ok():
    return {"status": "ok"}

@app.get("/not-found")
def not_found():
    raise HTTPException(status_code=404, detail="Resource not found")

@app.get("/crash")
def crash():
    # Simulates an unexpected bug
    result = 1 / 0  # noqa: F841
    return {"result": result}

@app.get("/key-error")
def key_error():
    data = {}
    return data["missing_key"]

# --- Test ---
client = TestClient(app, raise_server_exceptions=False)

# Normal response
print(f"OK: {client.get('/ok').json()}")

# HTTPException -> specific handler
resp = client.get("/not-found")
print(f"404: {resp.json()['error']['code']}")

# ZeroDivisionError -> global handler
resp = client.get("/crash")
print(f"500: {resp.status_code} {resp.json()['error']['code']}")
print(f"Has request_id: {'request_id' in resp.json()['error']}")

# KeyError -> global handler
resp = client.get("/key-error")
print(f"KeyError: {resp.status_code} {resp.json()['error']['code']}")

OK: {'status': 'ok'}
404: HTTP_404
ERROR: [<id>] Unhandled ZeroDivisionError on GET /crash: division by zero
500: 500 INTERNAL_ERROR
Has request_id: True
ERROR: [<id>] Unhandled KeyError on GET /key-error: 'missing_key'
KeyError: 500 INTERNAL_ERROR

Key Points

•@app.exception_handler(Exception) is the global catch-all -- it runs only when no other handler matches
•Include a request_id in the response so users can report issues and you can find the matching server log
•Log full error details server-side (type, message, traceback) but return a generic message to the client
•TestClient needs raise_server_exceptions=False to test 500 responses instead of re-raising

Gotchas

•The Exception handler does NOT catch HTTPException or RequestValidationError -- those have their own built-in handlers that take priority
•If you do not set raise_server_exceptions=False in TestClient, it re-raises the exception instead of returning the 500 response
•Do not return exc details in production -- stack traces, file paths, and SQL queries are security risks
•The global handler also catches CancelledError in some ASGI servers -- be careful with blanket Exception catching

Register @app.exception_handler(Exception) as a catch-all for unhandled errors. Log the full error server-side, generate a request ID for tracing, and return a generic 500 response. Use TestClient(app, raise_server_exceptions=False) to test it.

•Exception handler is the last resort -- catches anything not handled by specific handlers

import uuid
import logging
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

logger = logging.getLogger("api")
app = FastAPI()

@app.exception_handler(Exception)
async def catch_all(request: Request, exc: Exception):
    rid = str(uuid.uuid4())[:8]
    logger.exception(f"[{rid}] {type(exc).__name__}: {exc}")
    return JSONResponse(
        status_code=500,
        content={"error": "Internal error", "request_id": rid},
    )

TestClient re-raises exceptions by default -- use raise_server_exceptions=False to test 500 responses

Built by onllm.dev

Home GitHub Support awesomePrep