🔥 Erreur 429 API : retries bornés + backoff exponentiel
Découvrez comment gérer l’erreur 429 API : retries bornés, backoff exponentiel, Retry-After et idempotence pour limiter la débit et protéger vos alertes.
Erreur 429 : fiabiliser les alertes sans créer une panne en cascade
Une API de notification renvoie une erreur 429 quand elle vous demande de ralentir. La réaction la plus tentante est de relancer tout de suite, jusqu'à obtenir une réponse positive. En production, ça transforme facilement une limitation temporaire en vague de requêtes : les autres messages prennent du retard, et les coûts deviennent pénibles à attribuer.
La bonne réponse n'est pas de réessayer sans fin. Traitez le 429 comme un signal de contrôle : attendre, appliquer un nombre maximal de tentatives, puis arrêter explicitement le traitement si le fournisseur reste indisponible. Et surtout : chaque tentative doit garder le même identifiant de livraison. Sinon, vous finissez par mélanger une notification réessayée avec une nouvelle demande métier.
Ce guide propose une politique de reprise concrète pour un service d'alertes ou de notifications média : calcul du délai, prise en compte de Retry-After, idempotence, journalisation et escalade. Il explique aussi les limites de l'approche et ce que la supervision peut (ou ne peut pas) remplacer dans votre architecture.
Pourquoi un 429 doit changer l'ordonnancement
Une réponse HTTP 429 n'a pas le même sens qu'une erreur de validation ou qu'un incident réseau. Ici, le fournisseur vous dit que vous dépassez une limite de débit - globale, ou liée à une clé, un compte, ou une ressource. Ce n'est donc pas « réessayez tout de suite » : il faut replanifier.
Dans un service média, la notification reste la même opération métier : même campagne, même destinataire, même livraison attendue. Le 429 ne doit pas déclencher un nouvel envoi. Cette distinction évite les doublons côté destinataire et permet d'attribuer correctement la consommation à la campagne (ou au client) concerné.
Le risque de la relance immédiate
Si plusieurs travailleurs reçoivent un 429 en même temps et relancent aussitôt, ils repartent tous frapper l'API au même instant. Le fournisseur répond à nouveau 429, la file grossit, et les travailleurs consomment des ressources sans avancer. Et paradoxalement, c'est souvent le moment où votre service en a le moins.
Une boucle de relance sans garde-fous n'est donc pas une vraie stratégie de résilience. Elle décale juste la douleur dans le temps, sans garantir que la livraison aboutira. Elle peut aussi masquer l'incident : la requête reste « en cours » alors que la notification est déjà trop ancienne pour être utile.
Séparer le transport de la décision métier
Le travailleur devrait au moins distinguer trois cas : livraison acceptée, échec temporaire réessayable, et échec définitif. Une réponse 2xx indique généralement que le fournisseur a accepté la demande, pas que l'utilisateur a forcément reçu le message.
Une règle pratique aide beaucoup : garder une seule identité de livraison sur toute la durée du traitement. Chaque tentative augmente un compteur, mais ne crée pas une nouvelle notification. Si une nouvelle demande métier sort réellement du système (une nouvelle campagne, un nouvel événement), elle reçoit un nouvel identifiant. Cette frontière rend les volumes, la facturation et les investigations beaucoup plus fiables.
Quelles données conserver pour suivre les livraisons
Un compteur de tentatives est utile pour diagnostiquer. Mais il ne suffit pas pour comprendre ce qui a été envoyé, ce qui reste dû, et comment attribuer le coût. Il faut distinguer l'identité stable de la livraison de l'identité propre à chaque tentative.
Définir une identité et des événements cohérents
Pour une livraison, utilisez une clé stable : par exemple un identifiant de notification, ou un identifiant de destinataire associé à la campagne. Chaque appel au fournisseur doit aussi porter un identifiant de tentative (ou un identifiant d'essai). Ainsi, quatre tentatives pour une même notification restent « une livraison » dans vos rapports métier.
Un événement structuré pour la reprise peut inclure :
- l'identifiant de livraison et celui de la tentative ;
- le fournisseur, et éventuellement le compte ou la région concerné(e) ;
- l'identifiant de campagne ou de client, selon vos règles de cloisonnement ;
- le code HTTP, l'heure de la réponse et le délai de reprise calculé ;
- l'état final : acceptée, abandonnée, mise en quarantaine, ou en attente ;
- un identifiant de trace ou de segment, si vous en avez déjà un.
Évitez de copier le contenu du message dans les journaux par défaut. Pour les systèmes opérant en France ou dans l'Union européenne, la minimisation des données compte aussi pour le RGPD : les journaux doivent expliquer la décision et permettre la corrélation, sans dupliquer des données personnelles ni le texte de la notification.
Suivre le coût sans confondre tentatives et demandes
Pour attribuer les coûts, séparez « les livraisons demandées » du « nombre d'appels réellement passés ». Une tentative supplémentaire peut coûter au fournisseur, même si elle ne crée pas une nouvelle demande côté client. Avec un identifiant stable, vous consolidez ces dimensions sans facturer quatre notifications là où une seule a été demandée.
Un modèle événementiel raisonnable peut produire : un événement à la réception d'un 429, un autre quand la reprise est planifiée, puis un événement terminal au succès ou à l'abandon. Cette granularité aide les investigations, mais augmente le volume de données. Si le trafic est élevé, limitez-vous à l'essentiel et complétez par des métriques agrégées : taux de 429, tentatives par livraison, et part des notifications qui épuisent leur budget.
Définissez aussi un indicateur de service aligné sur la réalité. Par exemple : la proportion de notifications acceptées par le fournisseur avant une échéance métier, et l'âge de la livraison la plus ancienne en attente. Une latence moyenne faible peut masquer une file qui s'accumule en arrière-plan.
Quel dispositif de supervision choisir
La reprise appartient au service qui connaît la livraison, son identifiant et sa durée de validité. La supervision, elle, doit surtout faire remonter les tendances : hausse durable des 429, augmentation de l'âge de la file, ou dépassement du budget de tentatives. Mélanger ces responsabilités dans une même boucle de relance rend le système plus dur à comprendre.
Comparer selon la responsabilité à couvrir
Les outils de suivi d'erreurs, les plateformes d'observabilité et les systèmes d'alerte ne répondent pas exactement au même besoin. Le choix dépend de ce que vous avez déjà , et de ce que votre équipe est prête à opérer.
| Option | Intérêt principal | Limite à prévoir |
|---|---|---|
| Sentry | Regrouper les erreurs applicatives et faciliter l'analyse d'opérations qui échouent | Ne remplace ni l'ordonnanceur de livraison ni l'idempotence dans le travailleur |
| Datadog | Rassembler métriques, journaux et règles d'alerte dans un environnement opérationnel étendu | La configuration et la maintenance de la plateforme deviennent une responsabilité supplémentaire |
| Grafana Cloud | Relier tableaux de bord, métriques et règles d'alerte dans des équipes déjà organisées autour de Grafana | Un tableau de bord ne produit pas une reprise idempotente et ne définit pas la logique métier |
| Une API d'observabilité en REST | Envoyer des événements depuis différents langages sans dépendre d'un client dédié pour chaque environnement | Vérifiez la recherche, la rétention, les règles d'alerte et les modes d'escalade disponibles |
Une interface HTTP uniforme peut réduire le nombre de bibliothèques à maintenir dans une architecture multi-langages. Mais c'est un avantage d'intégration, pas une garantie « clé en main » pour la gestion d'incident. Avant de trancher, testez concrètement : seuils, rétention, recherche par identifiant, et envoi d'alertes.
Ne pas alerter sur chaque reprise
Une tentative de reprise est généralement un événement normal. Ce n'est pas, à elle seule, un incident. Notifier à chaque 429 crée du bruit et détourne l'attention des problèmes qui persistent.
Il vaut mieux déclencher une alerte sur une tendance ou un seuil métier : proportion de livraisons en échec, âge de la file, nombre de campagnes affectées, ou taux de réponses 429 sur une fenêtre donnée.
Et attention : des journaux ou des métriques ne garantissent pas, à eux seuls, que quelqu'un sera prévenu. Si votre plateforme ne propose pas de règles et de canaux d'escalade adaptés, mettez en place un mécanisme séparé (vérification périodique, gestionnaire d'alertes, ou astreinte). Si le système de supervision peut aussi s'arrêter, surveillez son exécution avec un contrôle de santé indépendant.
Conclusion
Face à un 429, le bon comportement consiste à ralentir sans perdre l'identité de la livraison. Un backoff exponentiel avec jitter, un plafond de délai, une limite de tentatives, et la prise en compte de Retry-After protègent à la fois le fournisseur et votre file.
Le reste se joue aussi après la réponse HTTP : rendez chaque tentative observable, distinguez clairement livraison et appel, préservez l'idempotence, et prévoyez une sortie terminale. Enfin, gardez la reprise séparée de l'escalade. Avant de déployer, validez vos paramètres avec le quota réel du fournisseur, votre SLO de livraison, et le coût d'une notification trop tardive.
Comment construire des reprises fiables
Une politique de reprise utile combine un délai qui augmente, une limite de tentatives, une durée maximale d'attente et une sortie terminale. Ces paramètres ne doivent pas être « choisis parce qu'ils sont faciles à coder » : ils doivent coller à la fenêtre de validité de la notification et aux quotas du fournisseur.
Calculer un délai borné avec une part d'aléatoire
Un schéma classique est le backoff exponentiel : après chaque 429, le délai augmente. Par exemple, si l'attente initiale est de 250 ms, on obtient en théorie 250 ms, puis 500 ms, puis 1 s, puis 2 s. Un plafond évite qu'une livraison reste suspendue trop longtemps.
Ajoutez ensuite du jitter (une petite part d'aléatoire). Sans ça, des centaines de travailleurs qui ont reçu la même réponse se remettent à relancer ensemble. Le jitter étale les tentatives et casse les vagues synchronisées.
Votre politique devrait expliciter :
Exemple : cinq tentatives « au total » peuvent convenir pour un flux, mais ce n'est pas universel. Une alerte urgente n'a pas forcément besoin d'attendre longtemps. Un message non urgent tolère peut-être une reprise plus lente. En pratique, vous ajustez selon le quota, le débit habituel, l'âge maximal acceptable en file, et la valeur métier d'une livraison tardive.
Respecter
Retry-Aftersans perdre le contrĂ´leCertains fournisseurs indiquent explicitement le moment de reprise via l'en-tĂŞte
Retry-After. Quand il est présent et valide, il doit guider l'ordonnancement : vous n'avez pas besoin de « deviner » un délai que le fournisseur vient de donner. La valeur peut être un nombre de secondes ou une date, selon la spécification utilisée.Mais ce n'est pas un chèque en blanc. Gardez vos garde-fous : délai maximal, limite de tentatives, et vérification que la reprise reste faisable dans la fenêtre de livraison. Si le délai annoncé dépasse votre budget, placez le message en file différée ou terminez-le selon une règle claire - ne bloquez pas un travailleur pendant des heures.
Garder le traitement annulable et durable
Une attente doit pouvoir être interrompue si votre service s'arrête, si la notification n'a plus de sens (expiration métier), ou si le contexte est annulé. Attendre « en dur » avec un temporisateur bloquant immobilise des ressources et rend les déploiements plus pénibles.
Dans un système basé sur une file de messages, il est souvent préférable de planifier la prochaine tentative dans la file plutôt que de faire dormir un travailleur. Pour que ça marche, il faut enregistrer durablement le moment de reprise et l'état de la livraison. Le travailleur peut alors s'arrêter sans perdre le rendez-vous, et la capacité reste disponible pour d'autres messages.