Séparer statut, type et occurrence
RFC 9457 définit notamment le format application/problem+json. Utilisez un type de problème stable et un détail compréhensible pour cette occurrence ; le client ne devrait pas analyser une phrase traduite pour décider. Si le membre status est présent, gardez-le cohérent avec le statut HTTP transmis.
| Statut | Interprétation HTTP | Conduite à examiner |
|---|---|---|
| 400 | Requête incorrecte | Corriger la requête avant une nouvelle tentative. |
| 401 | Authentification valide absente | Vérifier les justificatifs et le mécanisme prévu. |
| 403 | Requête comprise mais refusée | Examiner les droits ; une répétition identique ne les crée pas. |
| 503 | Service temporairement indisponible | Attente et reprise bornée si l’opération le permet. |
Rendre les chemins d’échec prévisibles
- Documentez les codes, les formats et la conduite attendue. Testez aussi réponse vide, contenu non JSON d’une passerelle, connexion interrompue et expiration.
- Validez les entrées et les autorisations côté serveur. Traitez les erreurs attendues sans masquer les anomalies inconnues ; n’utilisez pas une réponse de succès pour cacher un échec métier.
- Retournez un identifiant de corrélation utilisable par le support. Gardez traces de pile, requêtes internes, mots de passe et jetons hors des réponses publiques.
Reprendre seulement lorsque cela a un sens
La classe 5xx n’autorise pas une boucle de reprises sans limite. Combinez contrat, état de l’opération, idempotence et délai total. Pour signaler un défaut, fournissez une reproduction minimale et expurgée ; vérifiez ensuite le cas original et les refus d’accès voisins.
Références primaires
Pour approfondir
Erreurs API : identifier la suite sans divulguer
Le statut HTTP donne une première catégorie, mais le client peut avoir besoin d’un type stable et d’un détail utile. RFC 9457 décrit une structure commune de problème ; elle ne justifie pas d’exposer une trace interne ou des données sensibles.
- Distinguer refus permanent, entrée corrigeable et panne temporaire.
- Documenter type, statut et action client possible pour chaque erreur importante.
- Tester que les réponses ne contiennent ni secret ni charge complète inutile.
Référence primaire : IETF RFC 9457 — Problem Details for HTTP APIs. Méthode connexe : consulter le guide pratique.
Reprises API : compter le budget de bout en bout
Une politique d’erreur doit préciser les cas rejouables, le nombre total d’appels et l’échéance. Le calcul qui suit aide à repérer une configuration qui dépasse déjà son budget avant de tester les effets métier.
Cas pédagogique fictif — les chiffres ne décrivent pas CIE ni un client.
Le scénario fictif comprend quatre tentatives au total, chacune limitée à 250 ms, avec des attentes déterministes de 100, 200 et 400 ms. Le budget modélisé vaut 1 700 ms : 1 000 ms d’appels et 700 ms d’attentes. Il dépasse une échéance de 1 500 ms, avant même les autres coûts du parcours.
- Tentatives au total
- 4Une initiale et trois reprises
- Attentes cumulées
- 700 ms100 + 200 + 400
- Budget modélisé
- 1 700 ms4 × 250 + 700
| Étape | Délai maximal de l’appel | Attente avant l’appel suivant |
|---|---|---|
| Tentative 1 | 250 ms | 100 ms |
| Tentative 2 | 250 ms | 200 ms |
| Tentative 3 | 250 ms | 400 ms |
| Tentative 4 | 250 ms | Aucune |
| Total | 1 000 ms | 700 ms |
- Appels1 000 ms
- Attentes700 ms
- Échéance saisie1 500 ms
Contrôles pour interpréter le cas
- Propager une échéance globale et borner chaque appel par le temps restant. Ne pas empiler des politiques de reprise indépendantes entre couches.
- Vérifier si l’opération peut être répétée sans effet doublé. Un délai dépassé ne prouve pas que le serveur distant a arrêté le traitement.
- Le modèle ne comprend pas jitter, plafonds, Retry-After, résolution DNS, connexion, file d’attente ni validation locale. Mesurer ces coûts avant de configurer le service.
Quand une reprise aggrave la panne
Le budget de durée n’est qu’une condition. Une opération peut être assez rapide tout en étant dangereuse à répéter ou en multipliant la charge sur un fournisseur indisponible.
| Signal à examiner | Vérification concrète | Conséquence pour la décision |
|---|---|---|
| Action non idempotente | Vérifier la clé, sa portée et la conservation du résultat côté service. | Réconcilier l’état avant de répéter une création ou un paiement. |
| Reprises à plusieurs étages | Compter les tentatives du navigateur, de la passerelle et du service. | Attribuer la responsabilité des reprises et un budget de bout en bout. |
| Indisponibilité durable | Vérifier échéance, annulation et comportement du parcours sans le fournisseur. | Prévoir une dégradation explicite et une reprise contrôlée. |
Passer du chiffre à la vérification
Éprouver le scénario d’échec complet
- Test à reproduire
- Tester indisponibilité, réponse lente et perte de réponse après traitement. Vérifier l’idempotence avant toute reprise d’une écriture et compter aussi les reprises des couches intermédiaires.
- Signal d’arrêt
- Relancer une opération non idempotente sans savoir si la première tentative a produit son effet.
Changer une hypothèse
Réduire les essais sans créer de doublon métier
L’exemple précédent autorise quatre tentatives et atteint 1 700 ms. Voici ce que change un essai de moins, sans confondre budget théorique et durée observée.
- Trois tentatives
3 × 250 ms = 750 ms d’appels au maximum dans le modèle.
- Deux attentes
100 + 200 ms = 300 ms ; total modélisé : 1 050 ms.
- Échéance
Il reste 450 ms sur 1 500 ms pour les autres coûts, sans garantie qu’ils y tiennent.
Exercice de lecture : les variantes décrivent des situations fictives.
Et si la première tentative a déjà créé la commande ?
- Nouvel élément
- Le serveur a traité l’action, mais la réponse s’est perdue.
- Ce que cela change
- Un nouvel essai peut répéter l’effet métier. Vérifier l’idempotence ou retrouver l’état de l’opération avant de renvoyer l’action. Le calcul de délai ne résout pas ce problème.
Et si plusieurs couches relancent chacune trois fois ?
- Nouvel élément
- Dans un cas maximal simplifié, trois tentatives à chaque niveau sur trois niveaux peuvent produire 27 appels en aval.
- Ce que cela change
- Identifier la couche responsable des reprises et le budget global. La multiplication 3 × 3 × 3 décrit ce scénario, pas un volume systématique de production.
Pourquoi compter les tentatives plutôt que les reprises ?
Une tentative initiale plus trois reprises produit quatre appels. Employer des noms distincts évite une erreur d’une tentative dans la configuration et le calcul.
Essayer un budget de reprise
n × délai + attente × (2^(n−1) − 1). Attentes doublées, sans jitter ni plafonnement.
Méthode connexe : consulter le guide pratique.
Erreurs API : types, statuts et preuves
Traiter une erreur sans analyser sa phrase
Un client API peut recevoir un titre traduit, un membre manquant ou une extension qu’il ne connaît pas. Préservez une décision fondée sur le type documenté et le statut HTTP, puis associez une action sûre au contexte.
- Comparer statut reçu et status du JSON sans remplacer silencieusement l’un par l’autre.
- Tester un type absent, une chaîne à la place du nombre status et une extension inconnue.
- Séparer message destiné à la personne, code métier et référence d’occurrence.
Explorer les types de problèmes et les huit réponses fictives →
IETF · M. Nottingham, E. Wilde, S. Dalal · RFC 9457 · July 2023 · obsoletes RFC 7807 · §3.1, §3.2, §4.2, §5