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](#1-convention-rest--rfc-7807)
- [2. Matrice de Mapping Exceptions ➔ Codes HTTP](#2-matrice-de-mapping-exceptions--codes-http)
- [3. Format de Réponse (Problem Details)](#3-format-de-réponse-problem-details)
- [4. Distinctions 400 Bad Request vs 422 Unprocessable Content](#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 coeur 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`            | `Application`            | **404**   | `Resource Not Found`    | Ressource introuvable par le Use Case / 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 :

```json
{
  "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`).