Jérémy Munsch
b3f02510b5
Added a section for Exception Management in README and created a new document detailing exception handling and HTTP status codes.
60 lines
2.9 KiB
Markdown
60 lines
2.9 KiB
Markdown
# 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 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 :
|
|
|
|
```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`).
|