Comment gérez-vous les erreurs et levez des exceptions HTTP ?

Question

Accepted Answer

FastAPI gère les erreurs en **levant des exceptions** qu'il convertit en réponses HTTP appropriées. `HTTPException` couvre la plupart des cas ; les gestionnaires d'exception personnalisés vous permettent de contrôler le formatage des erreurs au niveau global.

## Lever 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=...)` est la façon idiomatique de retourner une erreur — FastAPI produit une réponse JSON `{"detail": "..."}` avec le statut donné. Le `detail` peut être n'importe quelle valeur sérialisable en JSON (chaîne, dict, liste).

## Les erreurs de validation sont automatiques (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.
```

## Gestionnaires d'exception personnalisés (formatage global)

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

Les gestionnaires d'exception personnalisés vous permettent de mapper vos propres exceptions (domaine) à des réponses, centralisant le formatage des erreurs et gardant le code du gestionnaire propre.

## Surcharger les gestionnaires par défaut

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

## Pourquoi c'est important

Une gestion appropriée des erreurs est essentielle pour construire des APIs fiables et professionnelles, et l'approche de FastAPI est claire et cohérente.

La `HTTPException` idiomatique rend facile le retour de réponses d'erreur correctes avec les codes de statut et les messages appropriés — fondamental pour tout endpoint qui peut échouer (non trouvé, interdit, mauvais état).

Également précieuse est le fait que **les erreurs de validation sont gérées automatiquement** (les défaillances Pydantic produisent des réponses structurées 422 sans code de votre part), et que **les gestionnaires d'exception personnalisés** vous permettent de mapper vos propres exceptions de domaine à des réponses et d'appliquer un format d'erreur cohérent sur toute l'API — améliorant à la fois la maintenabilité (logique d'erreur centralisée) et l'expérience client (formes d'erreur prévisibles).

Comprendre `HTTPException`, les erreurs de validation automatiques, et les gestionnaires personnalisés couvre le spectre pratique de la gestion des erreurs, ce qui en rend la connaissance importante pour construire des APIs robustes.