Gestion des erreurs Flask

Flask fournit un mécanisme flexible de gestion des erreurs qui peut intercepter et gérer diverses erreurs dans l'application.

Une bonne gestion des erreurs ne consiste pas seulement à « ne pas avoir de bugs » — il s'agit d'offrir aux utilisateurs une expérience conviviale lorsque des bugs surviennent.

Ce chapitre explique comment personnaliser les pages d'erreur et gérer les journaux dans Flask.


Page d'erreur personnalisée

Par défaut, Flask affiche une page simple avec fond noir et texte blanc pour les erreurs telles que 404.

Utilisation@app.errorhandlerLes décorateurs peuvent être utilisés pour personnaliser les pages d'erreur pour des codes d'état HTTP spécifiques :

Exemple

from flask import Flask, render_template

app = Flask(__name__)

# Gérer l'erreur 404 - page non trouvée
@app.errorhandler(404)
def page_not_found(error):
    # Remarque : il faut renvoyer explicitement le code d'état 404
    return render_template("404.html"), 404

# Gérer l'erreur 500 - erreur interne du serveur
@app.errorhandler(500)
def internal_error(error):
    return render_template("500.html"), 500

# Gérer l'erreur 403 - accès interdit
@app.errorhandler(403)
def forbidden(error):
    return render_template("403.html"), 403

Le modèle 404 correspondant :

Exemple

<!-- Chemin du fichier : templates/404.html -->
<!DOCTYPE html>
<html>
<head>
    <title>404 - Page introuvable</title>
    <style>
        body { text-align: center; padding-top: 60px; font-family: Arial; }
        h1 { font-size: 72px; color: #e74c3c; margin: 0; }
        p { color: #666; font-size: 18px; }
        a { color: #3498db; }
    </style>
</head>
<body>
    <h1>404</h1>
    <p>Désolé, la page que vous avez visitée n'existe pas.</p>
    <p><a href="/">Retour à l'accueil</a></p>
</body>
</html>

DanserrorhandlerDans la fonction décorée,returnVous devez spécifier explicitement le code d'état. Si vous ne l'écrivez pas, 404, Flask renverra un code d'état 200 par défaut, et les navigateurs et les moteurs de recherche ne le traiteront pas comme une page d'erreur.


Enregistrement de classe d'exception

Outre le code d'état,@app.errorhandlerVous pouvez également enregistrer directement des classes d'exception :

Exemple

from werkzeug.exceptions import HTTPException

@app.errorhandler(HTTPException)
def handle_http_exception(error):
    """Gérer toutes les exceptions HTTP uniformément (par exemple, 400, 401, 403, 404, etc.)"""
    return f"""
<h1>Erreur HTTP {error.code}</h1>
    <p>{error.description}</p>
<p><a href="/">Retour à la page d'accueil EXAMPLE</a></p>
    """
, error.code

Utilisation d'abort pour déclencher des erreurs

Dans votre fonction de vue, utilisezabort()pour déclencher activement une erreur HTTP :

Exemple

from flask import abort

# Simuler une base de données d'articles
articles = {
    1: {"title": Tutoriel Flask},
    2: {"title": "Bases de Python"},
}

@app.get("/article/<int:article_id>")
def view_article(article_id):
    article = articles.get(article_id)

    if article is None:
        # L'article n'existe pas, retourner 404
        # Le paramètre description sera passé à errorhandler
        abort(404, description=f"L'ID de l'article {article_id} n'existe pas")

    return f"<h1>{article['title']}</h1>"

@app.get("/admin")
def admin_panel():
    # Un utilisateur sans permissions d'administration accède au back-end d'administration
    abort(403, description="Vous n'avez pas les permissions d'administration")

Journalisation

Flask utilise le moduleloggingde la bibliothèque standard Python, viaapp.loggerVous pouvez alors journaliser l'enregistrement.

La journalisation est cruciale pour le dépannage — n'utilisez pas seulementprint(), car les journaux fournissent un contexte plus riche et un meilleur contrôle.

Exemple

from flask import Flask, request

app = Flask(__name__)

@app.route("/")
def index():
    # Différents niveaux de journalisation
    app.logger.debug("Accès à la page d'accueil")                    # Informations de débogage, généralement non affichées en production
    app.logger.info("Utilisateur depuis l'IP : %s", request.remote_addr)  # Informations générales
    app.logger.warning("Motif d'accès anormal détecté")         # Avertissement : nécessite une attention mais n'affecte pas le fonctionnement
    app.logger.error("Échec de la connexion à la base de données")               # Erreur : les fonctionnalités sont affectées
    app.logger.critical("Espace disque insuffisant, le service est sur le point de s'arrêter")  # Erreur critique : le service risque de s'arrêter
    return "OK"

Niveaux de journalisation (du plus bas au plus élevé) :

Niveau Cas d'utilisation
DEBUG Les informations détaillées pendant le débogage en développement ne sont pas émises par défaut dans l'environnement de production.
INFO Informations générales sur l'exécution, telles que les journaux de requêtes et le démarrage du service
WARNING Messages d'avertissement, problèmes potentiels qui n'affectent pas le fonctionnement actuel
ERROR Messages d'erreur, une fonctionnalité a échoué mais le service est toujours en cours d'exécution
CRITICAL Erreurs critiques, peuvent entraîner l'arrêt du service

En mode Debug, le niveau de journalisation de Flask est automatiquement défini surDEBUG. Dans les environnements de production, définissez-le selon les besoins surINFOouWARNING, pour éviter d'afficher trop d'informations inutiles.


Configurer la sortie des logs

Écrire les logs dans un fichier pour faciliter l'analyse a posteriori et le dépannage :

Exemple

import logging
from logging.handlers import RotatingFileHandler

# Configurer le gestionnaire de logs de fichier : effectuer une rotation une fois que le fichier de log atteint 10MB
handler = RotatingFileHandler(
    "example_app.log",     # Chemin du fichier de log
    maxBytes=10 * 1024 * 1024,  # Taille maximale d'un seul fichier 10MB
    backupCount=5          # Conserver les 5 dernières sauvegardes
)

# Définir le format des logs
handler.setFormatter(logging.Formatter(
    "[%(asctime)s] %(levelname)s in %(module)s: %(message)s"
))

# Ajouter un gestionnaire au logger de Flask
app.logger.addHandler(handler)
app.logger.setLevel(logging.INFO)

Intercepter les exceptions non gérées

Utilisationapp.errorhandler(500)Vous pouvez intercepter les exceptions non gérées et les enregistrer dans les journaux :

Exemple

import traceback

@app.errorhandler(500)
def internal_error(error):
    # Enregistrer la trace complète de la pile d'exception
    app.logger.error("Erreur interne du serveur :\n%s", traceback.format_exc())

    # Afficher une page d'erreur conviviale à l'utilisateur
    return """
<h1>500 - Erreur interne du serveur</h1>
<p>Désolé, le serveur a rencontré une erreur inattendue. Nous avons enregistré le problème. Veuillez réessayer plus tard.</p>
<p>Si le problème persiste, veuillez contacter le support technique EXAMPLE.</p>
    """
, 500

Référence rapide des codes d'erreur HTTP courants

Code d'état Signification Causes courantes
400 Requête incorrecte Paramètres de requête mal formés, champs obligatoires manquants
401 Non autorisé Utilisateur non connecté ou échec de l'authentification
403 Interdit L'utilisateur est connecté mais n'a pas la permission d'accéder
404 Non trouvé La ressource (article, utilisateur, etc.) n'existe pas
405 Méthode non autorisée Utilisation d'une méthode HTTP incorrecte (par exemple, utiliser GET pour accéder à un point de terminaison POST)
500 Erreur interne du serveur Erreurs non gérées telles que les exceptions de code et les échecs de connexion à la base de données
autres extensions