Les erreurs font partie de l'experience dev
Les erreurs determinent la vitesse de recuperation des integrations. Un message vague ralentit tout le monde.
Une erreur structuree transforme un echec en action claire : corriger un champ, reauthentifier, ou reessayer plus tard.
Un seul schema d'erreur
Choisissez un schema et appliquez-le partout : code stable, message humain, details optionnels.
La coherence facilite les librairies clientes et reduit les cas particuliers.
Codes d'erreurs stables
Les messages changent, les codes doivent rester stables. Ils permettent aux clients d'implementer des comportements.
Des codes courts et documentes suffisent.
Validation par champ
Quand un payload est invalide, renvoyez les erreurs par champ. Cela aide le client a cibler le probleme.
Un format simple est `errors: [{ field: 'email', message: 'invalid' }]`.
Ne pas exposer les details internes
Ne renvoyez jamais de stack trace. Loggez les details cote serveur avec un identifiant de correlation.
Retournez un message securise et utile pour le developpeur.
Echecs partiels explicites
Les batchs peuvent etre partiellement reussis. Retournez un statut clair et des resultats par item.
Cela permet de relancer uniquement les elements en echec.
Documenter le catalogue d'erreurs
Un petit catalogue de codes et de corrections possibles vaut beaucoup. Il reduit le support et clarifie les integrations.
La documentation d'erreur doit etre courte, specifique et stable.