Gestion des erreurs

Statut

Document de cadrage backend — v1.0 — relu le 2026-05-10.

Principe général

L'API DMV est une API JSON pure. Toutes les réponses d'erreur sont au format JSON, sans exception.

Ce comportement est forcé dans bootstrap/app.php :

$exceptions->shouldRenderJsonWhen(
    fn (Request $request, Throwable $e) => true
);

Exceptions métier mappées

Deux exceptions métier ont un rendu personnalisé :

ScopeViolationException → 403

{
  "error": "scope_violation",
  "message": "..."
}

Levée quand une action dépasse le périmètre autorisé d'un acteur (ex : modifier une publication hors de son contexte).

InvalidModerationActionException → 422

{
  "error": "invalid_moderation_action",
  "message": "..."
}

Levée quand une action de modération est invalide pour l'état actuel du contenu.

Erreurs des middlewares

Middleware	Erreur	Code
identify.app	missing_app_source	400
identify.app	unknown_app_source	400
device.token	missing_device_token	401
device.token	invalid_device_token	401
Auth Supabase	invalid_token	401

Format de réponse standard

Toutes les erreurs retournent un objet JSON avec au minimum :

{
  "error": "code_machine",
  "message": "Description lisible."
}

Les erreurs de validation Laravel (422) retournent aussi un champ errors avec le détail par champ.

Codes HTTP utilisés

Code	Usage
400	Requête malformée, header manquant
401	Authentification manquante ou invalide
403	Accès refusé, scope violé
404	Ressource introuvable
422	Validation échouée, action invalide
500	Erreur serveur non anticipée

Règles

• Ne jamais retourner de HTML en réponse à une erreur.
• Ne jamais exposer de trace de pile en production (APP_DEBUG=false).
• Ne jamais inclure de secrets ou données personnelles dans les messages d'erreur.
• Utiliser des codes machine stables (error) séparés des messages lisibles (message).
• Lever des exceptions métier typées plutôt que des codes retour génériques.

Points à clarifier

• Centralisation des codes d'erreur machine dans une enum ou constante.
• Logging automatique des 500 avec contexte utilisateur (sans données sensibles).
• Stratégie de retry pour les erreurs temporaires côté client.