Gestion des erreurs FastAPI

Dans le développement d'API, il est nécessaire de renvoyer des informations d'erreur au client. FastAPI fournitHTTPExceptionpour lever des erreurs HTTP, et prend également en charge des gestionnaires d'exceptions personnalisés pour gérer des scénarios d'erreur plus complexes.


Utiliser HTTPException

Lorsque vous devez renvoyer une réponse d'erreur, levezHTTPException:

Exemple

from fastapi import FastAPI, HTTPException

app = FastAPI()

items = {"foo": "The Foo Wrestlers", "bar": "The Bar Fighters"}


@app.get("/items/{item_id}")
async def read_item(item_id: str):
    if item_id not in items:
        # Lorsque la ressource n'existe pas, lever une erreur 404
        raise HTTPException(status_code=404, detail="Item not found")
    return {"item": items[item_id]}

Visitezhttp://127.0.0.1:8000/items/42Lorsque vous le ferez, vous obtiendrez :

{
    "detail": "Item not found"
}

Le code d'état HTTP est404。

Notez que ce qui est utilisé ici estraiseau lieu dereturn。HTTPExceptionest une exception. Après qu’elle est levée, FastAPI l’intercepte et renvoie la réponse d’erreur HTTP correspondante. Cela est cohérent avec le mécanisme de gestion des exceptions de Python.


Paramètres de HTTPException

ParamètreTypeDescription
status_codeintCode d’état HTTP (obligatoire)
detailAnyLes détails de l’erreur peuvent être une chaîne, un dictionnaire, une liste, etc.
headersdict | NoneEn-têtes de réponse supplémentaires (facultatif)

Détails d’erreur personnalisés

detailLe paramètre peut être de n’importe quel type, sans se limiter aux chaînes de caractères :

Exemple

from fastapi import FastAPI, HTTPException

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str):
    if item_id == "invalid":
        # detail peut être un dict contenant plus d’informations sur l’erreur
        raise HTTPException(
            status_code=400,
            detail={
                "error_code": "INVALID_ID",
                "message": "Le format de l'identifiant produit est incorrect",
                "hint": "Veuillez utiliser un identifiant alphanumérique"
            }
        )
    return {"item_id": item_id}

Ajouter des en-têtes de réponse personnalisés

Dans certains scénarios, vous devez ajouter des en-têtes de réponse personnalisés à la réponse d'erreur :

Exemple

from fastapi import FastAPI, HTTPException

app = FastAPI()


@app.get("/items-header/{item_id}")
async def read_item_header(item_id: str):
    if item_id == "invalid":
        raise HTTPException(
            status_code=404,
            detail="Item not found",
            headers={"X-Error": "There goes my error"},  # En-têtes de réponse personnalisés
        )
    return {"item": item_id}

Dans les scénarios où vous devez limiter la fréquence des requêtes client (limitation de débit), vous pouvez ajouter aux en-têtes de réponse d'erreurRetry-Afterun en-tête, indiquant au client quand il peut réessayer.


Gestionnaire d'exceptions personnalisé

Vous pouvez enregistrer des gestionnaires pour des exceptions personnalisées ou des exceptions intégrées afin de gérer uniformément le format de la réponse d'erreur :

Exemple

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


# Classe d'exception personnalisée
class UnicornException(Exception):
    def __init__(self, name: str):
        self.name = name


app = FastAPI()


# Enregistrer le gestionnaire d'exceptions
@app.exception_handler(UnicornException)
async def unicorn_exception_handler(request: Request, exc: UnicornException):
    # Renvoyer une réponse d'erreur au format personnalisé
    return JSONResponse(
        status_code=418,
        content={"message": f"Oups ! {exc.name} a fait quelque chose de mal"},
    )


@app.get("/unicorns/{name}")
async def read_unicorn(name: str):
    if name == "yolo":
        # Lever une exception personnalisée
        raise UnicornException(name=name)
    return {"unicorn_name": name}

Surcharger le gestionnaire d'exceptions par défaut

FastAPI dispose de gestionnaires d'exceptions par défaut. Vous pouvez les surcharger pour personnaliser le format de réponse d'erreur :

Exemple

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

app = FastAPI()


# Surcharger le gestionnaire d'exceptions HTTP
@app.exception_handler(StarletteHTTPException)
async def http_exception_handler(request: Request, exc: StarletteHTTPException):
    return JSONResponse(
        status_code=exc.status_code,
        content={"erreur": f"Erreur HTTP : {exc.detail}"},
    )


# Surcharger le gestionnaire d'exceptions de validation des requêtes
@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc: RequestValidationError):
    return JSONResponse(
        status_code=422,
        content={"erreur": "Échec de la validation des données", "détails": exc.errors()},
    )

RequestValidationErrorest une exception levée par FastAPI lorsque la validation des données de la requête échoue. Surcharger son gestionnaire permet de personnaliser le format de réponse pour les erreurs de validation.


Redirect

UtilisationRedirectResponseImplémenter la redirection :

Exemple

from fastapi import FastAPI
from fastapi.responses import RedirectResponse

app = FastAPI()


@app.get("/items/")
async def read_items():
    return {"items": ["foo", "bar"]}


@app.get("/redirect")
async def redirect():
    # Rediriger vers /items/
    return RedirectResponse(url="/items/")

En-têtes de réponse personnalisés et code de statut

UtilisationJSONResponseEn-têtes de réponse personnalisés et code de statut :

Exemple

from fastapi import FastAPI
from fastapi.responses import JSONResponse

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: int):
    content = {"item_id": item_id}
    headers = {"X-Custom-Header": "custom-header-value"}
    return JSONResponse(content=content, headers=headers)

Résumé

  • Utilisationraise HTTPExceptionRenvoyer une réponse d'erreur HTTP
  • detailLe paramètre peut être de n'importe quel type (chaîne, dictionnaire, liste, etc.)
  • Utilisation@app.exception_handlerEnregistrer un gestionnaire d'exceptions personnalisé
  • Vous pouvez remplacer les gestionnaires d'exceptions par défaut de FastAPI pour unifier le format des erreurs.
  • UtilisationRedirectResponseImplémenter la redirection
autres extensions