En bref
La RFC 9457 (Problem Details for HTTP APIs) est le format standard pour les réponses d'erreur des API. Elle remplace les formats d'erreur personnalisés par une structure cohérente : type, titre, statut, détail et instance. Modern PetstoreAPI implémente la RFC 9457 pour toutes les réponses d'erreur, avec une négociation de contenu et des détails de validation appropriés.
Introduction
Votre API renvoie une erreur. À quoi ressemble la réponse ? Si vous êtes comme la plupart des API, vous avez inventé votre propre format :
{"error": "Invalid email"}
{"message": "Not found", "code": 404}
{"success": false, "errors": ["Email required"]}
Chaque API a un format d'erreur différent. Les clients ont besoin d'une gestion des erreurs personnalisée pour chaque API. Il n'existe pas de méthode standard pour analyser les erreurs, les afficher aux utilisateurs ou les journaliser pour le débogage.
La RFC 9457 résout ce problème. C'est une norme de l'IETF qui définit comment les API doivent renvoyer les erreurs. Au lieu d'inventer votre propre format, vous utilisez une norme éprouvée que les clients comprennent déjà.
L'ancienne Swagger Petstore utilisait des formats d'erreur personnalisés sans cohérence. Modern PetstoreAPI implémente la RFC 9457 pour toutes les réponses d'erreur, fournissant des détails d'erreur structurés et lisibles par machine.
Dans ce guide, vous apprendrez ce qu'est la RFC 9457, comment l'implémenter correctement et comment Modern PetstoreAPI l'utilise pour toutes les réponses d'erreur.
Le problème des erreurs d'API
Avant la RFC 9457, chaque API inventait son propre format d'erreur.
Variations courantes des formats d'erreur
Format 1 : Message simple
{"error": "User not found"}
Format 2 : Code et message
{"code": "USER_NOT_FOUND", "message": "User not found"}
Format 3 : Structure imbriquée
{
"success": false,
"error": {
"type": "NotFound",
"message": "User not found"
}
}
Format 4 : Tableau d'erreurs
{
"errors": [
{"field": "email", "message": "Invalid email"}
]
}
Problèmes liés aux formats personnalisés
1. Manque de cohérence : Les clients ont besoin d'une analyse personnalisée pour chaque API.
2. Informations manquantes : Certains formats manquent de codes d'erreur, d'autres de détails, d'autres encore des deux.
3. Pas de structure lisible par machine : Difficile de gérer les erreurs par programmation.
4. Mauvaise internationalisation : Les messages d'erreur sont codés en dur en anglais.
5. Pas de standard pour les erreurs de validation : Chaque API gère les erreurs au niveau des champs différemment.
Qu'est-ce que la RFC 9457 ?
La RFC 9457 (publiée en juillet 2023) définit les « Problem Details for HTTP APIs ». C'est une norme de l'IETF qui spécifie comment les API doivent structurer les réponses d'erreur.
Fonctionnalités clés
Type de média standard : application/problem+json (ou application/problem+xml)
Structure cohérente : Toutes les erreurs suivent le même format
Lisible par machine : Les clients peuvent analyser les erreurs par programmation
Extensible : Vous pouvez ajouter des champs personnalisés tout en maintenant la compatibilité
Conscient de HTTP : S'intègre aux codes de statut HTTP
RFC 9457 vs Erreurs personnalisées
Erreur personnalisée :
{"error": "Email is required"}
Erreur RFC 9457 :
{
"type": "https://petstoreapi.com/errors/validation-error",
"title": "Erreur de validation",
"status": 400,
"detail": "The request contains invalid data",
"instance": "/pets",
"errors": [
{
"field": "email",
"message": "Email is required"
}
]
}
La version RFC 9457 fournit :
- URL du type d'erreur pour la documentation
- Titre lisible par un humain
- Code de statut HTTP
- Explication détaillée
- Chemin de la requête qui a causé l'erreur
- Détails de validation au niveau du champ
Structure de la RFC 9457 expliquée
La RFC 9457 définit cinq champs standard et autorise les extensions personnalisées.
Champs standard
1. type (chaîne, obligatoire)
Une référence URI identifiant le type d'erreur. Doit pointer vers une documentation lisible par un humain.
"type": "https://petstoreapi.com/errors/validation-error"
Si omis, la valeur par défaut est about:blank.
2. title (chaîne, obligatoire)
Un résumé court et lisible par un humain du type d'erreur. Ne doit pas changer entre les occurrences.
"title": "Validation Error"
3. status (nombre, obligatoire)
Le code de statut HTTP. Inclus par commodité afin que les clients n'aient pas besoin d'analyser les en-têtes.
"status": 400
4. detail (chaîne, facultatif)
Une explication lisible par un humain spécifique à cette occurrence de l'erreur.
"detail": "The email field must be a valid email address"
5. instance (chaîne, facultatif)
Une référence URI identifiant l'occurrence spécifique de l'erreur. Souvent, il s'agit du chemin de la requête.
"instance": "/pets/019b4132-70aa-764f-b315-e2803d882a24"
Extensions personnalisées
Vous pouvez ajouter des champs personnalisés pour un contexte supplémentaire :
{
"type": "https://petstoreapi.com/errors/rate-limit-exceeded",
"title": "Rate Limit Exceeded",
"status": 429,
"detail": "You have exceeded the rate limit of 100 requests per minute",
"instance": "/pets",
"retryAfter": 42,
"limit": 100,
"remaining": 0,
"resetAt": "2026-03-13T10:30:00Z"
}
Comment Modern PetstoreAPI implémente la RFC 9457
Modern PetstoreAPI utilise la RFC 9457 pour toutes les réponses d'erreur.
Exemple 1 : Ressource introuvable
GET /pets/invalid-id
404 Introuvable
Content-Type: application/problem+json
{
"type": "https://docs.petstoreapi.com/errors/not-found",
"title": "Ressource introuvable",
"status": 404,
"detail": "L'animal demandé n'existe pas",
"instance": "/pets/invalid-id"
}
Exemple 2 : Erreur d'authentification
GET /pets
401 Non autorisé
Content-Type: application/problem+json
{
"type": "https://docs.petstoreapi.com/errors/unauthorized",
"title": "Authentification requise",
"status": 401,
"detail": "Des identifiants d'authentification valides sont requis pour accéder à cette ressource",
"instance": "/pets"
}
Exemple 3 : Limite de débit dépassée
GET /pets
429 Trop de requêtes
Content-Type: application/problem+json
Retry-After: 60
{
"type": "https://docs.petstoreapi.com/errors/rate-limit-exceeded",
"title": "Limite de débit dépassée",
"status": 429,
"detail": "Vous avez dépassé la limite de débit de 100 requêtes par minute",
"instance": "/pets",
"limit": 100,
"remaining": 0,
"resetAt": "2026-03-13T10:31:00Z"
}
Consultez la documentation de gestion des erreurs de Modern PetstoreAPI pour tous les types d'erreurs.
Erreurs de validation avec la RFC 9457
Les erreurs de validation nécessitent des détails au niveau du champ. La RFC 9457 autorise les extensions personnalisées à cet effet.
Format de validation de Modern PetstoreAPI
POST /pets
400 Requête incorrecte
Content-Type: application/problem+json
{
"type": "https://docs.petstoreapi.com/errors/validation-error",
"title": "Erreur de validation",
"status": 400,
"detail": "La requête contient 2 erreurs de validation",
"instance": "/pets",
"errors": [
{
"field": "name",
"message": "Le nom est requis",
"code": "REQUIRED_FIELD"
},
{
"field": "species",
"message": "L'espèce doit être l'une des suivantes : DOG, CAT, BIRD, FISH, REPTILE, OTHER",
"code": "INVALID_ENUM_VALUE",
"rejectedValue": "DRAGON"
}
]
}
Points clés
tableau errors : Contient les détails de validation au niveau du champ
field : Le chemin JSON vers le champ invalide
message : Message d'erreur lisible par un humain
code : Code d'erreur lisible par machine
rejectedValue : La valeur qui a été rejetée (facultatif)
Ce format permet aux clients de :
- Afficher les erreurs au niveau du champ dans les formulaires
- Mettre en évidence les champs invalides
- Fournir des messages d'erreur spécifiques
- Gérer les erreurs par programmation
Test des réponses d'erreur avec Apidog
Apidog vous aide à tester la conformité à la RFC 9457.
Cas de test : Erreur de validation
// Script de test Apidog
pm.test("Returns RFC 9457 error format", () => {
const response = pm.response.json();
// Vérifier les champs obligatoires
pm.expect(response).to.have.property("type");
pm.expect(response).to.have.property("title");
pm.expect(response).to.have.property("status");
// Vérifier que le statut correspond au statut HTTP
pm.expect(response.status).to.equal(pm.response.code);
// Vérifier le type de contenu
pm.expect(pm.response.headers.get("Content-Type"))
.to.include("application/problem+json");
});
pm.test("Validation errors include field details", () => {
const response = pm.response.json();
pm.expect(response).to.have.property("errors");
pm.expect(response.errors).to.be.an("array");
response.errors.forEach(error => {
pm.expect(error).to.have.property("field");
pm.expect(error).to.have.property("message");
});
});
Cas de test : URLs de type d'erreur
pm.test("Error type URL is accessible", async () => {
const response = pm.response.json();
const typeUrl = response.type;
// Vérifier que l'URL du type renvoie de la documentation
const docResponse = await pm.sendRequest(typeUrl);
pm.expect(docResponse.code).to.equal(200);
});
Migration depuis les formats d'erreur personnalisés
Si vous utilisez des formats d'erreur personnalisés, voici comment migrer vers la RFC 9457.
Étape 1 : Ajouter l'en-tête Content-Type
Commencez à renvoyer application/problem+json :
Content-Type: application/problem+json
Étape 2 : Mapper les champs existants
Mappez votre format personnalisé à la RFC 9457 :
Avant :
{
"error": "USER_NOT_FOUND",
"message": "User not found"
}
Après :
{
"type": "https://api.example.com/errors/user-not-found",
"title": "Utilisateur introuvable",
"status": 404,
"detail": "Utilisateur introuvable"
}
Étape 3 : Supporter les deux formats (Période de transition)
Utilisez la négociation de contenu pour supporter les deux formats :
Accept: application/json → Renvoie le format personnalisé
Accept: application/problem+json → Renvoie le format RFC 9457
Étape 4 : Déprécier le format personnalisé
Après la migration des clients, dépréciez le format personnalisé et renvoyez la RFC 9457 par défaut.
Conclusion
La RFC 9457 fournit un format standard pour les réponses d'erreur des API. Elle remplace les formats d'erreur personnalisés par une structure cohérente et lisible par machine que les clients peuvent analyser par programmation.
Modern PetstoreAPI implémente la RFC 9457 pour toutes les réponses d'erreur, démontrant comment structurer correctement les erreurs avec des détails de validation appropriés, des URLs de type d'erreur et des codes de statut HTTP.
Utilisez Apidog pour tester la conformité à la RFC 9457, valider les structures d'erreur et vous assurer que votre API renvoie des réponses d'erreur appropriées.
FAQ
La RFC 9457 est-elle obligatoire pour les API REST ?
Non, mais c'est la norme recommandée. L'utilisation de la RFC 9457 rend votre API plus cohérente et plus facile à intégrer pour les clients.
Puis-je utiliser la RFC 9457 avec XML ?
Oui, la RFC 9457 définit les formats JSON (application/problem+json) et XML (application/problem+xml).
Dois-je toujours inclure les cinq champs standard ?
type, title et status sont obligatoires. detail et instance sont facultatifs mais recommandés pour un meilleur contexte d'erreur.
Puis-je ajouter des champs personnalisés aux réponses RFC 9457 ?
Oui, la RFC 9457 est extensible. Vous pouvez ajouter des champs personnalisés comme errors, retryAfter ou traceId pour un contexte supplémentaire.
Comment gérer les erreurs de validation avec la RFC 9457 ?
Ajoutez un tableau errors personnalisé avec les détails au niveau du champ. Modern PetstoreAPI présente ce modèle dans ses réponses d'erreur de validation.
Vers quoi doit pointer l'URL du type d'erreur ?
Elle doit pointer vers une documentation lisible par un humain expliquant le type d'erreur, les causes possibles et comment la corriger.
Dois-je modifier les codes de statut HTTP lorsque j'utilise la RFC 9457 ?
Non, la RFC 9457 fonctionne avec les codes de statut HTTP standard. Le champ status dans la réponse doit correspondre au code de statut HTTP.
Comment tester la conformité à la RFC 9457 ?
Utilisez Apidog pour valider la structure des réponses d'erreur, vérifier les champs obligatoires et s'assurer que les types de contenu correspondent aux spécifications de la RFC 9457.