Come gestisci gli errori e sollevi eccezioni HTTP?

Question

Accepted Answer

FastAPI gestisce gli errori **sollevando eccezioni** che converte in risposte HTTP appropriate. `HTTPException` copre la maggior parte dei casi; i gestori di eccezioni personalizzati ti permettono di controllare il formato degli errori globalmente.

## Sollevare 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=...)` è il modo idiomatico per restituire un errore — FastAPI produce una risposta JSON `{"detail": "..."}` con lo status fornito. `detail` può essere qualsiasi valore serializzabile JSON (stringa, dizionario, lista).

## Gli errori di validazione sono automatici (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.
```

## Gestori di eccezioni personalizzati (formattazione globale)

```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
```

I gestori di eccezioni personalizzati ti permettono di mappare le tue proprie eccezioni (di dominio) a risposte, centralizzando la formattazione degli errori e mantenendo il codice dei gestori pulito.

## Sovrescrivere i gestori predefiniti

```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()})
```

## Perché è importante

Una gestione appropriata degli errori è essenziale per costruire API affidabili e professionali, e l'approccio di FastAPI è pulito e coerente.

L'idiomatica `HTTPException` rende facile restituire risposte di errore corrette con i codici di stato e i messaggi appropriati — fondamentale per qualsiasi endpoint che può fallire (non trovato, vietato, stato errato).

Egualmente prezioso è che **gli errori di validazione sono gestiti automaticamente** (gli errori Pydantic producono risposte strutturate 422 senza codice da te), e che **i gestori di eccezioni personalizzati** ti permettono di mappare le tue proprie eccezioni di dominio a risposte e di applicare un formato di errore coerente in tutta l'API — migliorando sia la manutenibilità (logica degli errori centralizzata) che l'esperienza del client (forme di errore prevedibili).

Comprendere `HTTPException`, gli errori di validazione automatici e i gestori personalizzati copre lo spettro pratico della gestione degli errori, rendendo importante la conoscenza per costruire API robuste.