
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.
Reprendre un conflit sans supprimer sa cause
Scénario fictif : Une modification fondée sur une lecture ancienne reçoit une réponse de conflit. Relisez la représentation et identifiez les champs encore voulus avant une nouvelle tentative.
| Point | Preuve | Contrôle proposé |
|---|---|---|
| Contrat à conserver | Version avant changement | Faire préciser ce qui est fourni et ce que le traitement peut conclure. |
| Résultat à rapprocher | Réponse de conflit et état relu | Comparer le résultat effectivement observé à celui attendu pour ce cas. |
| Décision de reprise | Le traitement n’enlève pas automatiquement sa condition pour réussir. | Attribuer la suite et garder l’inconnue visible tant que la preuve manque. |
Le traitement n’enlève pas automatiquement sa condition pour réussir.
Cadre documentaire : IETF HTTP Working Group : RFC 9110, HTTP Semantics — référence consultée le . Sémantique HTTP documentée ; présence des ETag et prise en charge de ces conditions à confirmer pour chaque endpoint.
Stripe : distinguer les règles d’idempotence v1 et v2
La documentation distingue les générations d’API. La même expression « requête idempotente » ne suffit pas à décrire les conditions d’une reprise.
| Point documenté | Ce que la source précise | Conséquence pour votre contrôle |
|---|---|---|
| API v1 | Une fois l’exécution commencée, le premier statut et le corps sont conservés pour la clé, y compris une réponse 500. | Relire l’objet et l’état de l’opération avant de changer de clé après une erreur. |
| Durée de conservation v1 | Une clé peut être supprimée après au moins 24 heures ; sa réutilisation après suppression peut démarrer une nouvelle requête. | Conserver aussi un identifiant métier durable ; la clé HTTP n’est pas une protection permanente. |
| Paramètres | Stripe compare les paramètres d’une reprise avec ceux de la première requête. | Ne pas réutiliser une clé pour un montant ou un bénéficiaire différent. |
| API v2 | La documentation décrit une reprise des requêtes incomplètes ou échouées lorsque c’est possible, avec une réponse pouvant être actualisée. | Lire la règle de la version appelée au lieu de transposer automatiquement celle de v1. |
| Périmètre de reprise /v2 | Même clé pour la même API, dans le même compte ou sandbox et dans un délai de 30 jours. | Noter le namespace, le compte et la date initiale ; une version Stripe ne remplace pas ces informations. |
Ces règles concernent Stripe ; elles ne confirment ni la prestation touristique ni le traitement idempotent d’un second système.
Stripe — Idempotent requests · consultée le . Les contrôles proposés sont une lecture éditoriale de cette référence.
Stripe — périmètre et reprise dans /v2 · consultée le 27/10/2026
HTTP : revalider une lecture et protéger une écriture
Le validateur d’une représentation et la condition envoyée au serveur répondent à des usages différents. Un ETag n’est pas en lui-même une durée de validité commerciale.
| Point documenté | Ce que la source précise | Conséquence pour votre contrôle |
|---|---|---|
| If-Match | Utilise la comparaison forte des entity-tags. | Protéger une modification contre l’écrasement d’une représentation qui a changé. |
| If-None-Match | Utilise la comparaison faible ; une lecture GET ou HEAD peut recevoir 304 si la condition correspond. | Réutiliser la représentation conservée avec ses métadonnées au lieu d’attendre un nouveau corps. |
| Échec de précondition | Une précondition non satisfaite peut conduire à 412 selon la méthode et la condition. | Relire l’état et traiter le conflit avant de renvoyer une écriture ; ne pas transformer ce résultat en confirmation. |
La prise en charge des conditions par l’opération du fournisseur doit être confirmée dans sa documentation.
IETF — RFC 9110, conditions et validateurs · consultée le . Les contrôles proposés sont une lecture éditoriale de cette référence.
Postmark : un code d’erreur peut arrêter les notifications
La réponse du point de réception détermine si Postmark retentera de transmettre un événement sortant.
| Point documenté | Ce que la source précise | Conséquence pour votre contrôle |
|---|---|---|
| Nouvelle tentative | Les erreurs 5xx, 408, 429 et les échecs réseau donnent lieu à des reprises. | Conserver l’événement et surveiller la récupération du service. |
| Arrêt de l’événement | Les autres erreurs 4xx, dont 401, 403, 404 et 422, ne sont pas retentées. | Ne pas compter sur une nouvelle tentative automatique après une erreur d’authentification ou une URL incorrecte. |
| Accusé de réception | Postmark demande une réponse 200 après traitement ou remise à une file durable. | Distinguer réception technique, sauvegarde durable et traitement métier. |
| Vérification | Une défaillance persistante peut suspendre un type d’événement jusqu’à correction et nouvelle vérification. | Contrôler les statuts Delivery et Bounce séparément ; une catégorie qui fonctionne ne prouve pas que l’autre fonctionne. |
| Authentification | Postmark ne fournit pas de signature HMAC ; sa documentation recommande HTTP Basic Authentication en HTTPS et un filtrage des adresses IP. | Contrôler le mécanisme du fournisseur, puis la structure du message, au lieu d’attendre un en-tête de signature inexistant. |
Comportement des webhooks sortants Postmark ; les messages entrants utilisent une infrastructure distincte.
Postmark — Webhooks overview, retry attempts · consultée le . Les contrôles proposés sont une lecture éditoriale de cette référence.
Hostaway : lire le compteur atteint, pas seulement le code 429
Une limite peut dépendre du compte, de l’adresse IP ou de l’opération. Une seule cadence globale ne décrit donc pas tous les traitements Hostaway.
| Point documenté | Ce que la source précise | Conséquence pour votre contrôle |
|---|---|---|
| Limites générales | Pour les autres endpoints du tableau, Hostaway indique 200 requêtes par dix secondes, par compte et par adresse IP. | Des comptes distincts derrière une même IP peuvent partager cette contrainte ; répartir les comptes ne suffit pas à écarter le compteur IP. |
| Envoi de message | POST /v1/conversations/{id}/messages possède un compteur distinct de 30 requêtes par minute et par compte. | Séparez la file des messages des lectures de réservation ; ne lui appliquez pas le budget général par dix secondes. |
| Fenêtre glissante | Les compteurs portent sur les dix dernières secondes ou la dernière minute, sans remise à zéro à une frontière d’horloge fixe. | Passer à la minute suivante n’efface pas automatiquement la charge des dernières secondes. |
| Origine du blocage | Sur une réponse 429, X-RateLimit-Applied indique notamment endpoint, account, ip ou provider. | Conservez cet en-tête pour diagnostiquer le compteur atteint, avec l’échéance documentée du prochain essai. |
Relire deux rafales fictives
Comptages simplifiés pour comprendre les limites standard ; aucun trafic n’est envoyé.
Deux comptes distincts partagent la même adresse IP
Les deux traitements appellent des endpoints relevant des limites générales.
Compte A : 150 requêtes dans les dix secondes
Compte B : 80 requêtes dans les mêmes dix secondes
Même IP : 230 requêtes au totalLecture du cas. Chaque compte reste sous 200 dans le cas fictif, mais la somme sur l’IP dépasse 200. Examinez le compteur IP plutôt que de multiplier les nouvelles tentatives depuis la même sortie réseau.
Un envoi de message utilise le budget des lectures
Un programme prévoit 40 messages dans une minute sur le même compte.
Opération : envoi de message de conversation
Demandes fictives : 40 dans une minute
Budget standard documenté : 30 par minuteLecture du cas. Le compteur des messages est distinct. Une cadence admissible pour un autre endpoint ne rend pas cette rafale admissible ; gardez les messages en file avec leur suivi propre.
Limites standard de Hostaway Public API consultées le 23 octobre 2026. D’autres opérations ont leur propre ligne de limite et des augmentations peuvent être accordées ; relisez les paramètres du compte.
Hostaway Public API — Rate limits · consultée le . Les contrôles proposés sont une lecture éditoriale de cette référence.
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 )
- IETF HTTP Working Group : RFC 9110, HTTP Semantics : Sémantique HTTP documentée ; présence des ETag et prise en charge de ces conditions à confirmer pour chaque endpoint. (consultée le )
- Stripe — Idempotent requests : Ces règles concernent Stripe ; elles ne confirment ni la prestation touristique ni le traitement idempotent d’un second système. (consultée le )
- IETF — RFC 9110, conditions et validateurs : La prise en charge des conditions par l’opération du fournisseur doit être confirmée dans sa documentation. (consultée le )
- Postmark — Webhooks overview, retry attempts : Comportement des webhooks sortants Postmark ; les messages entrants utilisent une infrastructure distincte. (consultée le )
- Hostaway Public API — Rate limits : Limites standard de Hostaway Public API consultées le 23 octobre 2026. D’autres opérations ont leur propre ligne de limite et des augmentations peuvent être accordées ; relisez les paramètres du compte. (consultée le )
Questions fréquentes
Questions utiles avant de décider
Une erreur 429 signifie-t-elle que l’offre n’existe plus ?
Non. Le statut 429 signale une limitation du nombre de requêtes ; il ne répond pas à la question du stock. Respectez la politique de reprise du fournisseur puis relisez les conditions devenues anciennes. Un écran ne doit pas traduire une limitation technique en « complet » sans résultat de disponibilité.
Faut-il toujours attendre une valeur Retry-After ?
Non : la RFC 6585 permet ce champ sans l’imposer. Utilisez sa valeur lorsqu’elle est fournie selon le contrat, avec une limite de tentatives et un arrêt prévus. Si elle manque, appliquez la stratégie documentée de votre intégration, sans lancer une boucle de répétition immédiate.
Peut-on répéter une création dont la réponse manque ?
Retrouvez d’abord l’état de la première intention et les règles de reprise de l’opération. Une lecture sans réponse et une création sans réponse n’ont pas les mêmes conséquences possibles. Si le résultat demeure inconnu, attribuez l’investigation et informez sur cet état au lieu de créer une seconde commande par défaut.
Reprendre un conflit sans supprimer sa cause : quelle preuve conserver ?
Conservez version avant changement, réponse de conflit et état relu et la décision attribuée. Le traitement n’enlève pas automatiquement sa condition pour réussir.
Un webhook Postmark en erreur 401 sera-t-il retenté automatiquement ?
Non pour un webhook sortant : les erreurs 4xx autres que 408 et 429 ne sont pas retentées. Corrigez l’authentification et contrôlez les événements manquants ainsi que l’état de vérification du webhook.
La minute suivante remet-elle automatiquement à zéro les limites Hostaway ?
Non. Hostaway documente des fenêtres glissantes. Le compteur garde les requêtes des dernières secondes ou de la dernière minute. L’origine de la limite et l’échéance de reprise se lisent dans la réponse 429.



