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.
| Réponse | Action par défaut |
|---|---|
429, E01003 | Attendez Retry-After, puis réessayez. |
500, 502, 503 ou 504 | Réessayez les lectures avec des délais croissants bornés ; les écritures suivent leur contrat d'idempotence. |
501 | Arrêtez et vérifiez quelle opération le serveur prend en charge. |
401 ou 403 | Corrigez l'identifiant ou ses permissions avant de réessayer. |
| Validation de champ ou entrée invalide | Corrigez les champs identifiés par la réponse. |
409, E01004 | Attendez la fin de l'opération en cours avant de réessayer. |
409, E01005 | Corrigez la réutilisation d'une clé d'idempotence avec une entrée différente. |
La garantie d'idempotence assure qu'une nouvelle tentative identique n'est acceptée qu'une seule fois pendant trois heures. Réessayez une écriture avec la même clé et une requête identique, en espaçant les tentatives de façon bornée. Après un délai d'attente dépassé ou un échec du serveur, vous ne savez pas si la requête a été acceptée. Changer de clé crée une opération distincte. Si les nouvelles tentatives sont épuisées ou si la période de conservation expire, considérez ce résultat comme non résolu jusqu'à son rapprochement.
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.
En bref
Comparez les codes, pas les messages.
Bird ne renomme et ne réutilise jamais les codes d'erreur, mais les messages lisibles peuvent changer.
Réessayez les échecs temporaires avec une limite.
Attendez en cas de limitation du débit et augmentez progressivement le délai en cas d'échec temporaire du serveur. Conservez la même clé et une requête identique pendant la fenêtre d'idempotence de trois heures.
Lisez les détails de validation.
E01001transporte les problèmes de champ dansdetails. Utilisez chaqueparampour associer son message au champ concerné.Prévoyez un traitement par défaut pour les erreurs inconnues.
Journalisez les codes inconnus et leurs identifiants de requête pour que les nouveaux échecs ne cassent pas votre gestionnaire.