ldc-arcadia-api/documentation/Exceptions.md

Gestion des Exceptions & Codes HTTP — Arcadia API

Ce document récapitule la stratégie de gestion des exceptions et la correspondance avec les codes de statut HTTP dans Arcadia API.

Sommaire

• 1. Convention REST & RFC 7807
• 2. Matrice de Mapping Exceptions ➔ Codes HTTP
• 3. Format de Réponse (Problem Details)
• 4. Distinctions 400 Bad Request vs 422 Unprocessable Content

---

1. Convention REST & RFC 7807

L'API exprime toutes les réponses d'erreur au format RFC 7807 / RFC 9457 Problem Details avec l'en-tête HTTP : Content-Type: application/problem+json

---

2. Matrice de Mapping Exceptions ➔ Codes HTTP

Type d'Exception	Couche Origine	Code HTTP	Titre RFC 7807	Usage & Description
ValidationException	Presentation	422	Unprocessable Entity	Échec de validation HTTP (FormRequest), champs invalides ou manquants.
DomainException	Domain	422	Unprocessable Entity	Violation d'un invariant ou d'une règle métier au cœur du Domaine (ex: ValueObject).
ConflictException	Domain / Application	409	Conflict	Conflit d'état métier (ex: compte déjà supprimé, ressource déjà existante/verrouillée).
NotFoundException	Domain / Application	404	Resource Not Found	Ressource introuvable dans le répertoire / BDD.
HttpExceptionInterface (403)	Presentation	403	Forbidden	Accès refusé par les politiques d'autorisation HTTP.
ThrottleRequestsException	Infra	429	Too Many Requests	Dépassement du quota de requêtes API (Rate Limiting).
Throwable / Exception	Transverse	500	Internal Server Error	Erreur système non captée (détails masqués hors mode debug).

---

3. Format de Réponse (Problem Details)

Chaque réponse d'erreur retourne une structure JSON standardisée :

{
  "type": "http://localhost/errors/422",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Invalid employee number format",
  "instance": "/api/v1/employees",
  "invalidParams": [
    {
      "name": "domain_invariant",
      "reason": "Invalid employee number format"
    }
  ]
}

---

4. Distinctions 400 Bad Request vs 422 Unprocessable Content

• HTTP 400 (Bad Request) : Réservé aux erreurs de syntaxe ou de structure HTTP (ex: JSON illisible, guillemets mal fermés, en-têtes HMAC malformés). Le serveur ne peut pas parser le message.
• HTTP 422 (Unprocessable Content) : Convention REST & Laravel. La requête est du JSON syntaxiquement valide, mais son contenu viole les règles de validation HTTP (FormRequest) ou les invariants du domaine métier (DomainException).