Messages d'erreur d'API selon la RFC 9457 (Problem Details)

Ce que c'est

La RFC 9457 remplace la RFC 7807 et décrit un objet JSON qu'un serveur envoie, avec le type de média application/problem+json (ou application/problem+xml), comme corps de réponse en cas d'erreur. Les champs : type — une URI qui identifie la classe d'erreur et fournit idéalement une description lorsqu'on y accède ; en son absence, la valeur about:blank s'applique. title — un résumé court, identique pour toutes les occurrences de cette classe. status — le code de statut HTTP sous forme numérique. detail — une explication de cette occurrence concrète. instance — une URI qui désigne cette occurrence. Des champs d'extension propres (« Extension Members ») sont explicitement prévus, par exemple une liste des erreurs de champs lors d'une validation.

Pourquoi c'est important

Le code de statut seul est trop grossier : deux réponses 409 peuvent signifier « version obsolète » et « nom déjà pris », et exiger des réactions différentes. Un client capable d'orienter son traitement selon type décide entre réessayer, recharger et abandonner, sans avoir à analyser un texte de message qui changera à la prochaine version. Pour des agents qui utilisent les API à partir de la documentation, un catalogue d'erreurs stable et documenté est la condition pour ne pas avoir à deviner.

Comment l'appliquer

• Un seul format d'erreur pour toutes les réponses non-2xx, défini une fois dans la description OpenAPI et référencé par chaque point d'accès.
• Par classe d'erreur, une URI type stable sous le domaine propre (par exemple https://api.example.ch/probleme/kontingent-erschoepft), pointant vers une page décrivant la signification, le statut habituel et la réaction recommandée ; la liste appartient à la documentation de l'API.
• type et title restent stables entre les versions ; seul detail décrit le cas particulier, et ne renvoie pas telles quelles les entrées de la personne utilisatrice.
• Transporter les indications de nouvelle tentative dans les en-têtes standard (Retry-After) ; l'objet de problème peut les mentionner en plus.
• Représenter les erreurs de validation comme un champ d'extension contenant une liste de chemin de champ, type d'erreur et message, afin qu'un client puisse afficher tous les défauts en une fois.
• Le status dans le corps doit correspondre au statut HTTP réellement envoyé ; la RFC qualifie ce champ d'indicatif, afin qu'un client connaisse le statut d'origine même lorsqu'un intermédiaire l'a modifié.

Pièges

Des traces de pile, des noms d'hôtes internes ou du SQL dans detail. Un statut 200 accompagné d'un objet d'erreur dans le corps, ce qui trompe à la fois les caches et les clients. Renommer des classes d'erreur sans délai de transition. Une URI type qui pointe vers une page 404. N'introduire le format que sur certains points d'accès, ce qui oblige les clients à disposer de deux analyseurs.