Comprendre les erreurs API partenaire (429, webhooks)

Ce guide s'adresse aux développeurs intégrant l'API partenaire Thaïs-PMS (endpoints du type /partner/resort/...). Il explique comment interpréter les principaux codes d'erreur HTTP rencontrés, en particulier le code 429 (Too Many Requests), et présente le principe général des webhooks comme alternative au polling répété.

Contexte

L'API partenaire Thaïs-PMS expose des ressources (réservations, achats, disponibilités, etc.) consommées par des systèmes tiers. Comme toute API mutualisée entre plusieurs intégrations, elle applique des mécanismes de protection contre les usages abusifs (rate limiting) et retourne des codes d'erreur HTTP standards que l'intégrateur doit savoir gérer correctement côté client.

Exemple de cas rencontré en support : une intégration interrogeait en boucle et à haute fréquence l'endpoint /partner/resort/purchases, provoquant des erreurs 429 persistantes. Ce type de situation est généralement le symptôme d'un polling trop agressif plutôt que d'un dysfonctionnement du serveur.

Code 429 — Too Many Requests

Signification

Le code 429 indique que le client a dépassé le nombre de requêtes autorisées sur une période donnée (rate limiting / limitation de débit). C'est un mécanisme de protection standard, présent sur la quasi-totalité des API publiques, destiné à garantir la stabilité du service pour l'ensemble des intégrations.

Une erreur 429 n'est pas une erreur applicative : elle ne signifie pas que la requête est incorrecte, mais que son rythme d'envoi doit être ajusté.

Bonnes pratiques standard à appliquer côté client

1. Respecter l'en-tête Retry-After, si présent dans la réponse.

De nombreuses API renvoient un header Retry-After (en secondes ou en date) indiquant le délai à attendre avant de réémettre une requête. Si ce header est présent dans la réponse Thaïs, il doit être prioritaire sur toute autre stratégie de retry.

ℹ️ La présence effective et le format exact de ce header sur l'API Thaïs restent à confirmer par l'équipe dev — ne pas supposer son existence sans l'avoir vérifié en conditions réelles.

2. Mettre en place un backoff exponentiel.

En l'absence de Retry-After exploitable, retenter la requête avec un délai croissant entre chaque tentative (ex. 1s, 2s, 4s, 8s...), idéalement avec un peu de variation aléatoire (jitter) pour éviter que plusieurs clients ne retentent tous exactement au même moment.

3. Réduire la fréquence de polling.

Si votre intégration interroge un endpoint à intervalle fixe et rapproché (toutes les quelques secondes par exemple) pour détecter des changements, c'est souvent la cause racine des 429. Espacez les appels et évitez les boucles de vérification continue.

4. Privilégier les webhooks aux appels répétés (polling).

Lorsque l'objectif est d'être notifié en temps quasi réel d'un événement (nouvelle réservation, nouvel achat, mise à jour de statut...), un mécanisme de webhook est généralement bien plus adapté qu'une boucle de polling — voir section dédiée ci-dessous.

5. Mettre en cache les résultats lorsque c'est pertinent, pour éviter de redemander une information qui n'a pas changé entre deux appels.
6. Ne jamais retenter en boucle sans délai. Retenter immédiatement une requête ayant reçu un 429 ne fait qu'aggraver la situation et retarde la levée de la limitation.

En cas de 429 persistant malgré ces bonnes pratiques

Si les 429 persistent après mise en place d'un backoff et d'une réduction de fréquence raisonnable, il est probable que :

• le volume de requêtes nécessaire à votre cas d'usage dépasse la limite standard prévue pour votre intégration ;
• ou qu'un webhook existe pour votre besoin et devrait remplacer le polling actuel.

Dans ce cas, contactez le support Thaïs en précisant l'endpoint concerné, la fréquence d'appel actuelle, et le cas d'usage métier — l'équipe pourra évaluer si une limite spécifique doit être ajustée ou si une alternative (webhook) est disponible.

Autres codes HTTP courants

Cette liste couvre les codes HTTP génériques les plus fréquemment rencontrés. D'autres codes (400, 409, 503...) peuvent exister selon les endpoints ; leur documentation précise doit être confirmée avec l'équipe dev Thaïs.

Webhooks : principe général

Polling vs webhooks

• Polling : le client interroge activement l'API à intervalles réguliers pour vérifier si une donnée a changé (« y a-t-il du nouveau ? »). Cette approche est simple à mettre en œuvre mais génère un volume de requêtes proportionnel à la fréquence d'interrogation, indépendamment du nombre réel d'événements — c'est une cause fréquente d'erreurs 429 lorsque l'intervalle est trop court.
• Webhook : à l'inverse, c'est le serveur (Thaïs) qui notifie activement le système du partenaire dès qu'un événement pertinent se produit (ex. une nouvelle réservation, un achat, un changement de statut), en envoyant une requête HTTP (généralement en POST) vers une URL fournie par le partenaire lors de la configuration de l'intégration. Le partenaire n'a alors plus besoin d'interroger l'API en boucle : il reçoit l'information au moment où elle survient.

Pourquoi privilégier les webhooks quand ils sont disponibles

• Réduction drastique du nombre de requêtes, donc moins de risques de rencontrer des 429.
• Latence plus faible : l'information est reçue au moment de l'événement, pas au prochain cycle de polling.
• Charge réduite côté serveur Thaïs comme côté partenaire.

Points génériques à vérifier lors de l'intégration d'un webhook

Ces éléments sont valables pour la quasi-totalité des systèmes de webhooks du marché ; leur implémentation précise côté Thaïs doit être confirmée avec l'équipe dev avant intégration :

• URL de réception : l'endpoint exposé par le partenaire doit être accessible publiquement (HTTPS) et répondre rapidement (idéalement un code 2xx immédiat, le traitement métier étant fait de façon asynchrone).
• Sécurisation / vérification de l'origine : de nombreux systèmes de webhooks signent leurs requêtes (ex. via un en-tête de signature basé sur un secret partagé) afin que le récepteur puisse vérifier que la notification provient bien du système émetteur. (À confirmer : existence et mécanisme exact d'une signature côté Thaïs.)
• Gestion des échecs et des relances : si l'endpoint du partenaire est indisponible ou répond en erreur, l'émetteur peut retenter l'envoi selon une politique de relance (retry) propre à chaque système. (À confirmer : politique de retry exacte de Thaïs en cas d'échec de livraison.)
• Idempotence : un même événement peut, selon les systèmes, être livré plus d'une fois (ex. en cas de retry après timeout). Le traitement côté partenaire doit idéalement être conçu pour être rejouable sans effet de bord (ex. en s'appuyant sur un identifiant unique d'événement).
• Format de la charge utile (payload) : le format exact des données envoyées (structure JSON, champs disponibles, liste des types d'événements) est spécifique à chaque API et n'est pas détaillé dans ce document dans l'attente d'une confirmation par l'équipe dev Thaïs.

Résumé

• Une erreur 429 signale un dépassement de débit, pas un bug : ralentir les appels, respecter Retry-After s'il est présent, appliquer un backoff exponentiel.
• Les codes 401 / 403 concernent l'authentification et les permissions ; 404 une ressource introuvable ; 500 une erreur serveur à signaler au support avec l'identifiant de requête si disponible.
• Pour tout besoin de notification en temps réel (nouvelle réservation, achat, etc.), privilégier un webhook plutôt qu'un polling répété, afin de réduire la charge et les risques de 429.
• Les détails techniques précis de l'API Thaïs (limites de rate, headers exacts, format des webhooks, politique de retry) doivent être validés par l'équipe dev avant toute publication définitive de cette documentation.

Mis à jour le : 24/08/2026