Intégration et exploitation
API voyage : erreurs, quotas et reprises
Une erreur technique ne se traite pas toujours en renvoyant la même demande. La recherche d’un tarif, la lecture d’une réservation et sa création n’ont pas les mêmes effets. Le parcours doit reconnaître la cause connue, respecter les limites du fournisseur et préserver les références permettant de retrouver une opération dont la réponse manque.
Distinguer transport, statut HTTP et erreur métier
Conservez opération demandée, heure, statut HTTP, code métier et référence de corrélation lorsqu’elle existe. Une réponse HTTP exploitable peut contenir un refus métier ; une absence de réponse laisse parfois le résultat inconnu. Le support doit pouvoir expliquer ce qui est observé sans transformer une erreur de transport en preuve que la réservation n’existe pas.
Préparez des branches distinctes pour paramètre invalide, droit insuffisant, débit limité, indisponibilité temporaire et résultat incertain. L’équipe qui corrige une date n’est pas celle qui valide une permission. Un message unique « réessayez » empêche de distinguer ces actions et peut multiplier les demandes au moment où le fournisseur est déjà saturé.
Respecter une limite sans créer une nouvelle vague d’appels
La RFC 6585 définit le statut 429 comme une limitation du nombre de requêtes. La réponse peut inclure Retry-After ; ce champ n’est pas garanti. La norme ne fixe pas une règle unique de comptage : le quota réel, sa fenêtre et son périmètre doivent être lus dans la documentation du fournisseur.
Suivez séparément demandes utilisateur, appels émis et reprises. Pour une recherche, regrouper certaines demandes identiques ou afficher une attente peut être préférable à une répétition immédiate. Fixez un plafond de tentatives et une échéance utile au client. Lorsque le délai dépasse la durée de validité d’une offre, la reprise peut exiger une nouvelle recherche.
Décider si l’opération peut être répétée
La RFC 9110 distingue les méthodes idempotentes et encadre la répétition automatique des demandes non idempotentes. Cette propriété technique ne doit pas être déduite d’un nom de bouton. Pour une création de réservation ou un mouvement financier, vérifiez le mécanisme et les garanties effectivement documentés par le fournisseur.
Une clé d’idempotence doit rester liée à la même intention et au même contenu selon les règles du produit utilisé. Si la réponse d’une commande manque, recherchez d’abord ses références ou contactez le circuit prévu. Changer arbitrairement de clé ou de compte pour contourner une attente peut produire plusieurs opérations pour un seul choix du voyageur.
Préserver le dossier pendant l’attente
Exemple pédagogique : la recherche est limitée, une offre précédemment choisie expire et le client revient sur le formulaire. Le parcours relit prix et disponibilité avant toute nouvelle création. Il explique la fin de validité sans promettre de maintenir un prix ancien simplement parce que la carte reste affichée.
Attribuez l’attente à un dossier, avec état connu, dernière observation et prochaine action. Le voyageur retrouve ses critères et le support retrouve la tentative précédente. Si la réservation reste incertaine, évitez d’afficher simultanément « aucune réservation » et une invitation à payer de nouveau. La décision doit s’appuyer sur la lecture fournisseur.
Tester reprise, arrêt et retour au service
La recette inclut réponse 429 avec et sans délai, erreur métier dans une réponse reçue, délai dépassé puis résultat retrouvé, et arrêt au plafond de tentatives. Testez aussi la reprise par une autre équipe. Il faut retrouver l’action effectuée plutôt qu’une simple succession de messages d’erreur.
Utilisez la fiche de contrôle des reprises API et le registre des erreurs et reprises. Mesurez attentes résolues, répétitions évitées et dossiers encore incertains. Le nombre de réponses techniques finalement reçues ne mesure pas à lui seul le nombre de réservations servies.
Sources et périmètre des faits documentés
La date de consultation figure avec chaque référence. Les méthodes d’essai et recommandations de ce guide sont éditoriales ; les conditions d’accès et d’usage se vérifient dans la documentation actuelle.
- RFC 6585 : statut 429 — Signification de la limitation et caractère facultatif de Retry-After. (consultée le )
- RFC 9110 : méthodes idempotentes — Sémantique HTTP et conditions de répétition automatique ; le contrat métier reste propre au fournisseur. (consultée le )
Questions fréquentes
Questions utiles avant de décider
Une erreur 429 signifie-t-elle que l’offre n’existe plus ?
Elle indique une limitation de requêtes, pas un résultat de disponibilité. La validité de l’offre doit être relue lorsque la reprise redevient possible.
Faut-il toujours attendre une valeur Retry-After ?
Le fournisseur peut fournir ce champ, mais la RFC ne le rend pas obligatoire. Appliquez les consignes de son produit et une politique d’arrêt documentée.
Peut-on répéter une création dont la réponse manque ?
Il faut d’abord vérifier son résultat et le mécanisme d’idempotence documenté. Une réponse absente ne prouve pas l’absence de commande.