Comment concevoir des réponses d'erreur cohérentes et signaler les erreurs de validation ?

Question

IT Interview Practice · Accepted Answer

Une bonne réponse d'erreur fait deux choses : elle utilise le **bon status code HTTP** (le signal lisible par machine), et elle retourne un **body cohérent et structuré** sur lequel un développeur peut agir. Des formes d'erreur incohérentes sont l'une des plus grandes sources de douleur côté client.

## Utilisez un format d'erreur standard : RFC 7807 (problem+json)

La RFC 7807 définit un body standard de « problem details » avec un media type dédié, de sorte que chaque erreur de votre API a la même apparence :

```http
HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/not-found",
  "title": "Resource not found",
  "status": 404,
  "detail": "No user exists with id 999",
  "instance": "/users/999"
}
```

- `type` — un URI identifiant la catégorie d'erreur (déréférençable vers la doc).
- `title` — un résumé court et lisible par un humain (stable par `type`).
- `status` — le status HTTP, répété par commodité.
- `detail` — une explication spécifique à *cette* occurrence.
- `instance` — sur quelle requête/ressource cela s'est produit.

## Erreurs de validation : signalez-les toutes d'un coup

Pour la validation de formulaire/champ, retournez `422` (ou `400`) et un **tableau d'erreurs par champ** pour que le client puisse mettre en évidence chaque champ invalide en une seule passe — pas une erreur à la fois :

```http
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation failed",
  "status": 422,
  "errors": [
    { "field": "email", "code": "invalid_format", "message": "must be a valid email" },
    { "field": "age",   "code": "out_of_range",   "message": "must be >= 18" }
  ]
}
```

## Principes

```text
✓ Même forme de body pour chaque erreur (un seul chemin de code côté client)
✓ Un code lisible par machine et stable (type/code) — les clients s'y branchent, pas sur la prose
✓ Message lisible par un humain pour les développeurs/logs
✗ Ne jamais divulguer de stack traces, de SQL, ou de chemins internes aux clients
```

## Pourquoi c'est important

La conception des erreurs est là où les API réussissent ou échouent discrètement dans le monde réel : le happy path est facile, mais les consommateurs passent la majeure partie de leur temps de débogage dans le chemin d'erreur, et un contrat d'erreur incohérent ou vague rend l'intégration misérable. Les recruteurs s'en servent pour vérifier deux choses. D'abord, **le status code et le body structuré fonctionnant ensemble** — le status est le signal grossier pour l'outillage et les retries, le body porte le détail actionnable — plutôt que l'anti-pattern du `200 OK` avec une erreur à l'intérieur. Ensuite, un **code d'erreur stable et lisible par machine** (via le `type` de la RFC 7807 ou un champ `code`) pour que les clients se branchent sur `"insufficient_funds"` plutôt que de faire du string-matching sur un message en anglais qui pourrait être reformulé ou localisé. Retourner toutes les erreurs de validation d'un coup, et ne jamais divulguer de détails internes comme des stack traces, complète une réponse qui montre que vous avez construit des API que d'autres équipes ont réellement dû consommer.

Utilisez un format d'erreur standard : RFC 7807 (problem+json)

Erreurs de validation : signalez-les toutes d'un coup

Principes

Pourquoi c'est important

Questions connexes