Jérémy Munsch 0d2b0124ee docs(architecture): add global architecture documentation for Arcadia API

docs(architecture): add request lifecycle documentation for Arcadia API

docs(architecture): add execution, transactions, and domain events documentation for Arcadia API

docs(architecture): add guide for creating a new use case in Arcadia API

docs(exceptions): summarize exception handling and HTTP status codes in Arcadia API

docs(tests): outline testing strategy and conventions for Arcadia API

style(openapi): correct description formatting in OpenAPI documentation

chore: remove outdated exceptions documentation

test: remove obsolete tests documentation

2026-08-21 10:41:07 +02:00

3.4 KiB

Raw Blame History

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 standardisé 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: ressource déjà existante ou verrouillée).
`NotFoundException`	`Application`	404	`Resource Not Found`	Ressource introuvable par le Use Case ou le répertoire.
`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).

3.4 KiB Raw Blame History