Qu'est-ce qu'un catalogue d'erreurs et comment associer les codes d'erreur à des réessais ?

Une requête échouée peut nécessiter un délai, un champ corrigé ou un identifiant différent. La réponse d'erreur de Bird fournit des champs que votre gestionnaire peut utiliser pour choisir cette action.

Quels champs d'erreur utiliser ?

Utilisez type pour un traitement général et code pour une récupération spécifique. Bird place ces champs dans un objet error de premier niveau.

Le type regroupe les échecs tels que la validation, l'authentification et la limitation du débit. Le code identifie l'échec particulier, par exemple E01001 pour la validation de champ.

Bird ne renomme et ne réutilise jamais un code. Les codes retirés restent réservés, de sorte qu'une correspondance existante conserve sa signification.

Affichez ou journalisez message, mais ne comparez pas son texte. La formulation peut changer sans modifier l'échec que votre gestionnaire doit traiter.

Le name rend les journaux lisibles. Le doc_url renvoie vers la documentation du code. Journalisez code, name et request_id ensemble lorsqu'une opération échoue.

Quels échecs réessayer ?

Réessayez les échecs temporaires avec une politique bornée. Corrigez les problèmes d'entrée et d'identifiants avant de retenter. Vérifiez le code spécifique lorsqu'un même statut peut nécessiter des actions différentes.

Conservez la même clé d'idempotence lorsque vous réessayez la même écriture. Un délai d'attente ou un échec du serveur ne prouve pas que l'opération initiale n'a rien fait.

Arrêtez lorsque le budget de réessai est épuisé et enregistrez l'erreur finale. Répéter indéfiniment une requête inchangée peut masquer un échec nécessitant une intervention.

Comment gérer les erreurs de validation de champ ?

Lisez le tableau details sur E01001 ValidationError et associez chaque entrée à son param. Affichez le message de cette entrée à côté du champ concerné.

N'analysez pas ces messages pour identifier le champ ou l'échec. Leur formulation peut changer, tout comme le message de premier niveau.

Une requête malformée peut renvoyer E01002 InvalidRequest à la place. Utilisez sa récupération documentée plutôt que de supposer que chaque échec d'entrée contient des détails par champ.

La réponse peut-elle m'indiquer comment récupérer ?

Certaines erreurs incluent remediation, une étape suivante lisible, ou next, une liste ordonnée d'opérations à essayer.

Affichez la remédiation lorsqu'elle aide la personne à corriger le problème. Par exemple, un échec d'autorisation peut nécessiter un identifiant avec une portée supplémentaire.

Un gestionnaire automatisé peut utiliser next pour choisir une opération de récupération. Il a toujours besoin des entrées et des permissions de cette opération avant de l'exécuter.

Un vendor_code identifie un échec en aval, tel qu'une réponse SMTP ou un refus de paiement. Consultez le code de ce fournisseur lorsque la récupération en dépend.

Que faire face à un code inconnu ?

Conservez une branche par défaut qui enregistre l'échec sans planter ni réessayer indéfiniment. De nouveaux codes et types peuvent apparaître à mesure que le API s'enrichit.

Appliquez une politique de réessai connue basée sur le statut lorsque c'est pertinent. Sinon, arrêtez et journalisez le code avec son identifiant de requête pour investigation.

Le guide des erreurs documente la réponse d'erreur. La référence des erreurs liste les codes individuels et leurs indications de récupération.