Un code d’erreur API doit permettre au client de distinguer une correction de donnée, une absence de droit, une reprise possible et une panne temporaire.
Un message humain ne suffit pas pour un intégrateur. Le contrat doit définir le code, le statut HTTP, les champs concernés et l’action attendue. Les détails sensibles restent dans le serveur et un identifiant aide le support.
Stabiliser le contrat
Ne changez pas le sens d’un code existant sans version ou période de transition. Un nouveau champ d’erreur peut être ajouté si le client l’ignore correctement. Les tests de contrat vérifient les cas attendus.
Gérer les reprises
Une erreur temporaire indique si une nouvelle tentative est autorisée. L’écriture doit utiliser une clé d’idempotence pour éviter une double opération. Une erreur de validation doit retourner les champs et règles, sans révéler une donnée privée.
Observer
Mesurez les erreurs par route, version et client. Reliez-les à l’opération métier et à l’identifiant de corrélation. Les logs évitent le contenu complet des requêtes.
Sources : RFC 9110, HTTP, OpenAPI.
Documenter les réponses
Chaque erreur indique un identifiant, un statut, une cause lisible et une action. Un client peut corriger un champ, attendre, renouveler son authentification ou contacter le support. Les réponses ne révèlent pas si une donnée privée existe lorsque cette information est sensible.
Les tests couvrent les paramètres manquants, les droits, les limites, les doublons et les pannes. Une reprise doit utiliser une clé stable et ne pas créer deux écritures. Le contrat précise la durée de conservation d’un identifiant d’erreur.
Surveillez les erreurs par version et client. Une hausse après un déploiement déclenche une comparaison du contrat et des données. Le propriétaire décide si une version doit rester supportée ou être retirée.