How do you handle errors and raise HTTP exceptions?

Question

Accepted Answer

FastAPI handles errors by **raising exceptions** that it converts into proper HTTP responses. `HTTPException` covers most cases; custom exception handlers let you control error formatting globally.

## Raising HTTPException

```python
from fastapi import HTTPException

@app.get("/items/{id}")
def get_item(id: int):
    item = db.get(id)
    if not item:
        raise HTTPException(status_code=404, detail="Item not found")   # → 404 JSON response
    if not item.is_public:
        raise HTTPException(status_code=403, detail="Forbidden")
    return item
```

`raise HTTPException(status_code=..., detail=...)` is the idiomatic way to return an error — FastAPI produces a JSON response `{"detail": "..."}` with the given status. The `detail` can be any JSON-serializable value (string, dict, list).

## Validation errors are automatic (422)

```text
When request data fails Pydantic validation, FastAPI AUTOMATICALLY returns a 422
with a structured list of exactly which fields are wrong — you write nothing.
```

## Custom exception handlers (global formatting)

```python
from fastapi import Request
from fastapi.responses import JSONResponse

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

@app.exception_handler(ItemNotFound)         # handle a custom exception type globally
def handle_not_found(request: Request, exc: ItemNotFound):
    return JSONResponse(status_code=404, content={"error": f"Item {exc.item_id} not found"})

@app.get("/items/{id}")
def get(id: int):
    raise ItemNotFound(id)        # raise your domain exception; the handler formats it
```

Custom exception handlers let you map your own (domain) exceptions to responses, centralizing error formatting and keeping handler code clean.

## Overriding default handlers

```python
from fastapi.exceptions import RequestValidationError

@app.exception_handler(RequestValidationError)   # customize the 422 validation-error format
def validation_handler(request, exc):
    return JSONResponse(status_code=422, content={"errors": exc.errors()})
```

## Why it matters

Proper error handling is essential for building reliable, professional APIs, and FastAPI's approach is clean and consistent.

The idiomatic `HTTPException` makes it easy to return correct error responses with appropriate status codes and messages — fundamental for any endpoint that can fail (not found, forbidden, bad state).

Equally valuable is that **validation errors are handled automatically** (Pydantic failures produce structured 422 responses with no code from you), and that **custom exception handlers** let you map your own domain exceptions to responses and enforce a consistent error format across the whole API — improving both maintainability (centralized error logic) and the client experience (predictable error shapes).

Understanding `HTTPException`, automatic validation errors, and custom handlers covers the practical spectrum of error handling, making it important knowledge for building robust APIs.