Résumé

  • RFC 7807, publié en mars 2016, a défini application/problem+json et son équivalent XML. L’URI type y sert déjà d’identifiant principal pour le logiciel client.
  • RFC 9457, publié en juillet 2023, a remplacé ce texte. Il précise le risque d’une URI relative, la rupture créée par un changement d’adresse et la manière de présenter plusieurs erreurs.
  • L’enregistrement officiel des types HTTP accueille les problèmes communs. about:blank, valeur implicite lorsque type manque, ne dit rien au-delà du code de statut.

Une réponse 403, plusieurs causes

La machine qui reçoit un 403 sait qu’une action a été refusée. Elle ne sait pas encore quelle décision commerciale ou technique l’a provoqué. Dans l’exemple publié par RFC 7807, un achat échoue faute de crédit. Le statut reste 403 pour les composants HTTP ordinaires ; le corps de la réponse précise le problème propre à l’application. Cette répartition évite de demander au registre des codes HTTP de décrire chaque cas d’usage d’une boutique, d’une banque ou d’un service de réservation.

Le document de 2016 a proposé un objet commun : type, title, status, detail, instance, avec la possibilité d’ajouter des champs propres au problème. Son exemple emploie un type « crédit insuffisant », indique le solde et renvoie vers des comptes pouvant être alimentés. Le format est partagé ; la signification du type spécifique est publiée par l’exploitant de l’API. Ce dernier choisit le nom de l’échec et la conduite qu’il attend du client.

Le choix du client doit porter sur type. RFC 7807 en fait l’identifiant principal. title est destiné à la lecture humaine et peut être localisé. detail raconte cet incident précis ; le texte déconseille d’y chercher des instructions à l’aide de chaînes de caractères. Un programme qui repère le mot « crédit » dans une phrase cesse de fonctionner dès que la phrase change. Une URI stable offre un point d’appui bien plus net.

instance remplit une autre fonction. Deux achats refusés pour le même manque de crédit relèvent du même type, mais peuvent recevoir deux identifiants d’incident. Le premier permet de reconnaître une classe d’échec ; le second peut aider un service d’assistance à retrouver un cas. Si un client prend chaque instance pour un type nouveau, il perd la possibilité de réutiliser la même règle d’action.

Le vide a aussi un nom

L’objet peut omettre type. Sa valeur est alors about:blank. Ce choix empêche l’habillage JSON de produire une précision imaginaire. Un 404 accompagné de about:blank dit ce que dit le 404. Pour annoncer un échec plus précis, l’éditeur doit lui donner une identité et en documenter le sens.

Le code de statut garde également son autorité sur l’infrastructure HTTP. Le champ status inclus dans le JSON est indicatif ; lorsqu’il est présent, le producteur doit le faire correspondre au véritable statut de la réponse. Un intermédiaire peut modifier le message, un journal peut conserver le corps séparément, mais un proxy ordinaire lit d’abord le statut HTTP. Le format d’erreur n’a pas transformé le corps JSON en tribunal d’appel des en-têtes.

Le prix d’une adresse qui dure

En 2023, RFC 9457 a maintenu cette architecture et explicité sa fragilité. Une URI relative telle que example-problem peut désigner deux ressources différentes selon l’adresse de la réponse. Le texte recommande donc une URI absolue lorsque c’est possible. Il admet aussi les URI impossibles à consulter. Mais passer plus tard d’une telle URI à une adresse consultable change l’identité du type et peut rompre les clients déjà écrits. Le propriétaire du nom doit vivre avec les conséquences de son choix initial.

La révision clarifie les erreurs multiples. Plusieurs champs invalides peuvent figurer dans une extension d’un même problème de validation. Lorsque des problèmes de types différents se présentent, le texte recommande d’afficher le plus pertinent ou le plus urgent. Un seul statut HTTP gouverne la réponse ; une collection indistincte d’échecs concurrents priverait le client d’une priorité lisible.

Le registre IANA, créé dans le cadre de RFC 9457, est réservé aux types communs et largement utilisables, selon une procédure exigeant une spécification. Il n’héberge pas la nomenclature privée de chaque application. L’institution a fourni une grammaire commune ; l’exploitant conserve la responsabilité de ses propres promesses.

Il manque un inventaire daté de réponses de services et de versions clientes pour mesurer l’adoption réelle. Les RFC établissent déjà le déplacement essentiel : une erreur destinée aux machines n’est plus seulement un nombre et une phrase. Elle porte une identité que quelqu’un doit maintenir.