Gestion des erreurs (Fast API)

Dans FastAPI, la gestion des erreurs consiste à intercepter et traiter les exceptions afin de renvoyer au client une réponse claire, structurée et conforme au format attendu (souvent JSON).
Cela permet d’éviter des messages d’erreur techniques non maîtrisés et d’améliorer l’expérience utilisateur ou développeur.

FastAPI repose sur Starlette, qui offre un système puissant de gestion des erreurs et des exceptions personnalisées.

Comment ça fonctionne dans FastAPI

Déclencher une erreur

Lever une HTTPException fournie par FastAPI, en précisant :
- le code HTTP (status_code),
- le message d’erreur (detail).
  Exemple :

Définir un gestionnaire d’erreurs personnalisé

Utiliser le décorateur @app.exception_handler(ExceptionType) pour capter une exception donnée et retourner une réponse formatée.
Ces gestionnaires peuvent renvoyer :
- du JSON structuré (souvent pour les API REST),
- une réponse HTML (si l’application est hybride),
- des en-têtes HTTP supplémentaires.

Codes HTTP courants

400 : Mauvaise requête (Bad Request)
401 : Non autorisé (Unauthorized)
403 : Accès interdit (Forbidden)
404 : Ressource non trouvée (Not Found)
422 : Données non valides (Unprocessable Entity) – utilisé automatiquement par FastAPI pour la validation.
500 : Erreur interne du serveur (Internal Server Error)

Exemple conceptuel

URL / endpoint : /products/{id}
Comportement : si l’ID du produit n’existe pas, lever HTTPException avec code 404 et message clair.
Méthode HTTP : GET
Réponse : JSON { "error": "Product not found" } avec code HTTP 404.

Bonnes pratiques

Toujours utiliser HTTPException plutôt que de laisser une erreur Python brute remonter.
Uniformiser le format de réponse pour toutes les erreurs (clé error ou detail).
Centraliser les gestionnaires dans un fichier dédié (errors.py ou similaire).
Tirer parti de la validation automatique de FastAPI avec Pydantic pour éviter beaucoup d’erreurs avant même le traitement.
Enregistrer un gestionnaire global pour capturer toutes les exceptions non prévues (Exception) et renvoyer un code 500 formaté.

Pourquoi c’est important

Évite d’exposer des messages techniques ou internes aux utilisateurs finaux.
Améliore la clarté et la cohérence des réponses d’erreurs.
Facilite l’intégration avec des clients ou frontends qui attendent un format spécifique.

En résumé

FastAPI utilise HTTPException pour signaler des erreurs contrôlées.
La validation Pydantic réduit fortement les erreurs de données entrantes.
Les gestionnaires personnalisés permettent un contrôle total sur la structure des réponses.

Fonctions :

Gestion des erreurs avec Fast API (exemple)

Exemple de code :

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

app = FastAPI()

# 1️⃣ Route normale
@app.get("/items/{item_id}")
def read_item(item_id: int):
    # Simuler une erreur si l'ID est négatif
    if item_id < 0:
        raise HTTPException(status_code=400, detail="ID invalide : doit être positif")
    return {"item_id": item_id, "name": f"Item {item_id}"}

# 2️⃣ Gestion globale des erreurs personnalisées
@app.exception_handler(Exception)
async def generic_exception_handler(request: Request, exc: Exception):
    return JSONResponse(
        status_code=500,
        content={"message": f"Une erreur est survenue : {str(exc)}"}
    )

Explication du code :

from fastapi import FastAPI, HTTPException, Request importe FastAPI pour créer l’application, HTTPException pour lever des erreurs HTTP spécifiques et Request pour accéder aux informations sur la requête dans les gestionnaires d’erreurs.
 from fastapi.responses import JSONResponse importe JSONResponse pour renvoyer des réponses JSON personnalisées lors d’erreurs.
Créer l’application FastAPI
 app = FastAPI() crée une instance de l’application qui servira à définir les routes et gérer les requêtes.
Route normale avec gestion d’erreur spécifique
 @app.get("/items/{item_id}") définit une route GET qui prend un paramètre dynamique item_id.
 def read_item(item_id: int): la fonction reçoit cet ID en tant qu’entier.
 if item_id < 0: vérifie si l’ID est négatif.
 raise HTTPException(status_code=400, detail="ID invalide : doit être positif") lève une exception HTTP 400 avec un message explicite si l’ID est invalide.
 return {"item_id": item_id, "name": f"Item {item_id}"} renvoie les informations de l’item si tout est correct.
Gestion globale des erreurs inattendues
 @app.exception_handler(Exception) définit un gestionnaire pour toutes les exceptions de type Exception non gérées par les routes.
 async def generic_exception_handler(request: Request, exc: Exception): la fonction reçoit la requête et l’exception.
 return JSONResponse(...) renvoie une réponse JSON avec :
 - status_code=500 pour indiquer une erreur serveur.
 - content={"message": f"Une erreur est survenue : {str(exc)}"} pour fournir un message clair avec le texte de l’erreur.