Jérémy Munsch
0d2b0124ee
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
62 lines
3.4 KiB
Markdown
62 lines
3.4 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 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 :
|
|
|
|
```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`).
|