Ressources · 77
Quotas API : limiter la charge et reprendre sans tempête de requêtes
Définir budgets, identités et reprises pour préserver le service lorsqu’un client atteint une limite.
· 11 min
Ce que ce guide permet
- Définir ce qui est limité
- Choisir le comportement de dépassement
- Encadrer les reprises
- Exercer saturation et rétablissement
- Attribuer la responsabilité des reprises
- Arrêter le travail devenu inutile
Contrôle express
- Un code 429 suffit-il à protéger le service ?
- Retry-After est-il toujours un nombre ?
- Peut-on réessayer toute requête automatiquement ?
- Trois tentatives à chaque couche font-elles trois tentatives au total ?
- L’expiration d’une tâche annule-t-elle son effet distant ?
Méthode pas à pas
- 01
Définir ce qui est limité
Distinguez nombre de requêtes, volume transféré, coût de calcul et opérations concurrentes. Choisissez une identité de comptage et un périmètre : client, compte, route ou service. Une IP partagée peut regrouper des personnes indépendantes ; une clé API par utilisateur ne suffit pas à limiter le coût global.
Livrable : unité, fenêtre et périmètre de chaque limite.
- 02
Choisir le comportement de dépassement
Précisez si une requête est refusée, mise en file ou servie en mode réduit. HTTP 429 exprime un excès de requêtes ; Retry-After peut indiquer une attente. Son absence ne donne pas au client le droit de réessayer en boucle. Les compteurs doivent rester cohérents avec le nombre d’instances et les routes coûteuses.
Livrable : réponses et règle de comptage.
- 03
Encadrer les reprises
Bornez nombre de tentatives et durée totale. Répartissez les reprises avec un délai progressif et une variation aléatoire. Respectez le délai reçu, avec gestion des horloges pour une date HTTP. Pour une opération à effet externe, vérifiez d’abord si elle a déjà abouti et utilisez une protection contre les doublons.
Livrable : politique client de reprise.
- 04
Exercer saturation et rétablissement
Dans un environnement autorisé, testez rafales, charge soutenue, clients partageant une IP, plusieurs instances et panne du compteur. Vérifiez que les tâches importantes restent disponibles et qu’un rétablissement ne relance pas tous les clients ensemble. Mesurez les refus justifiés et les utilisateurs bloqués à tort.
Livrable : essais reproductibles et décision de réglage.
- 05
Attribuer la responsabilité des reprises
Cartographiez application, SDK, proxy et dépendances avec leurs tentatives automatiques. Choisissez la couche responsable et désactivez ou coordonnez les reprises supplémentaires selon le contrat. Comptez la première tentative dans le budget total. Conservez l’identifiant métier et vérifiez les effets incertains avant de relancer une opération non idempotente.
Carte des reprises et budget total par opération.
- 06
Arrêter le travail devenu inutile
Définissez une échéance de bout en bout couvrant attente, connexion et traitement, avec les limites réelles du client utilisé. Refusez les tâches périmées avant leur admission en file. Une annulation locale ne prouve pas que le serveur s’est arrêté : rapprochez son état. Testez le retour progressif du trafic après panne sans réactiver simultanément toutes les files.
Échéance propagée et preuves d’arrêt ou de réconciliation.
Cas de recette à reproduire
Exemple fictif : ces données ne décrivent aucun client ni résultat réel.
Voir les données du cas
{
"http_status": 429,
"retry_after_seconds": 30,
"workers": 20,
"retry_budget": 3,
"retry_budget_scope": "per_worker_retries_excluding_initial_request",
"scheduling_example": {
"response_received_at_seconds": 0,
"illustrative_retry_seconds": [
30,
31,
32,
33,
34
],
"workers_per_second": 4,
"alternative_deadline_seconds": 25,
"total_attempts_if_all_retries_used": 80
}
}Décision attendue
Respecter l’attente de 30 secondes ; échelonner les reprises des 20 travailleurs et borner leur budget.
Vingt clients : répartir la reprise et compter les tentatives
Exemple fictif : 20 travailleurs reçoivent chacun à +0 s une réponse 429 avec Retry-After: 30. Les horaires ci-dessous illustrent une répartition possible, sans garantir la capacité du serveur. Le budget est de 3 reprises par travailleur, en plus de sa requête initiale.
| Politique | Calcul ou horaire | Ce que cela change |
|---|---|---|
| Reprise simultanée | 20 × 1 = 20 @ +30 s | Attendre 30 secondes respecte le délai, mais les 20 requêtes repartent au même instant : la rafale peut revenir. |
| Reprise répartie | 4 × 5 = 20 @ +30…+34 s | Quatre requêtes par seconde pendant cinq secondes répartissent les 20 reprises, sans en diminuer le nombre. Ce calendrier illustratif ne remplace pas une politique de temporisation avec variation aléatoire. |
| Échéance à 25 secondes | 25 s < 30 s → 0 | Si le temps restant est inférieur aux 30 secondes demandées, arrêter ou différer selon le contrat. Ne pas raccourcir le délai pour tenir l’échéance. |
| Budget maximal | 20 × (1 + 3) = 80 | Si toutes les tentatives sont utilisées, 20 requêtes initiales et 60 reprises donnent 80 requêtes au total. Le plafond ne garantit ni réussite ni innocuité d’une répétition. |
Variantes fictives à éprouver
Retry-After contient une date HTTP, pas des secondes.
Interpréter le format annoncé et contrôler l’horloge. Consigner l’attente calculée ; ne pas convertir la date en un délai arbitraire.
Chaque travailleur dispose de son propre budget de reprise.
Calculer aussi la charge cumulée. Coordonner le quota partagé et répartir les reprises pour éviter une nouvelle rafale synchronisée.
La réponse manque après une opération avec effet métier.
Vérifier l’état faisant foi et le contrat d’idempotence avant de rejouer. Un délai expiré ne démontre pas l’absence d’exécution.
Preuves à conserver
- En-têtes reçus, format de délai et horloge utilisée.
- Budget cumulé de tentatives et temps maximal.
- Identifiant d’opération et résultat rapproché.
Référence complémentaire : IETF — RFC 9110, Retry-After [EN]
Procédure de vérification
- Relevez quota, portée et budget de reprise.
- Épuisez le quota uniquement dans un test autorisé.
- Conservez 429, Retry-After et chronologie des reprises bornées. Distinguez la limitation technique du résultat métier : un quota épuisé ne doit pas devenir une réponse annonçant un stock nul.
- Dans une simulation sans charge externe, comptez les tentatives de quatre couches limitées chacune à trois appels totaux.
- Faites expirer une tâche fictive en file et vérifiez qu’elle ne démarre pas comme nouvelle opération.
- Réintroduisez progressivement les travaux autorisés après une panne simulée et conservez appels, échéances et résultats métier uniques.
Fiche de travail à réutiliser
À compléter avec vos observations autorisées. Ces champs constituent une trame de travail, pas des résultats observés.
| Champ | Information à consigner |
|---|---|
| Limite | Unité, fenêtre, identité et route |
| Dépassement | Réponse, délai et message utilisateur |
| Reprise | Budget d’essais, doublons et arrêt |
| Preuve | Charge testée, refus et retour à la normale |
API : éviter les reprises multipliées entre couches
Une application, son SDK, un proxy et un service peuvent chacun réessayer le même appel. Dans un exemple fictif où quatre couches font chacune trois tentatives au total, jusqu’à 81 appels atteignent la dépendance en échec. La méthode ci-dessous ajoute un budget partagé et une échéance utile aux contrôles de quota existants.
Exemple d’application
Situation illustrative
Exemple fictif : une synchronisation de catalogue reçoit 429 et tous les clients réessaient immédiatement.
Décision et preuve attendue
Le client respecte l’attente, répartit ses reprises, conserve un curseur et confirme les opérations déjà appliquées.
Distinguer les mécanismes
| Mécanisme | Utilité | Point de vigilance |
|---|---|---|
| Limite de débit | Encadrer les arrivées sur une fenêtre | Peut laisser passer des opérations lentes |
| Concurrence | Limiter les traitements simultanés | Ne borne pas seule l’usage mensuel |
| Quota de consommation | Encadrer un budget cumulé | Définir renouvellement et unité facturée |
Indicateurs de pilotage
| Indicateur | Ce qu’il mesure | Première action |
|---|---|---|
| Refus | Requêtes refusées par route et identité | Séparer abus et clients légitimes |
| Reprises utiles | Tentatives conduisant à un résultat unique | Réduire boucles et doublons |
| Amplification des appels | Appels à la dépendance / opérations métier initiales sur la même fenêtre | Séparer tentatives totales, reprises et sous-appels prévus |
| Travaux périmés admis | Tâches commencées après leur échéance utile | Mesurer aussi file, annulation et effets déjà engagés |
Erreurs fréquentes
- Peut laisser passer des opérations lentes
- Ne borne pas seule l’usage mensuel
- Définir renouvellement et unité facturée
Questions fréquentes
Un code 429 suffit-il à protéger le service ?
Non. Il décrit un refus. Il faut aussi contrôler coût, concurrence, files et comportement des clients.
Retry-After est-il toujours un nombre ?
Non. HTTP autorise une durée en secondes ou une date HTTP. Le client doit reconnaître les deux formes.
Peut-on réessayer toute requête automatiquement ?
Non. Pour un effet non idempotent, une réponse perdue peut masquer une opération réussie. La reprise doit vérifier l’état métier.
Trois tentatives à chaque couche font-elles trois tentatives au total ?
Non. Elles peuvent se multiplier. Dans la chaîne fictive de quatre couches, trois tentatives totales par couche donnent jusqu’à 3⁴ = 81 appels à la dernière dépendance.
L’expiration d’une tâche annule-t-elle son effet distant ?
Pas nécessairement. Elle doit empêcher les nouveaux travaux devenus inutiles ; un traitement distant déjà commencé exige un contrôle de son état et une compensation adaptée si elle existe.
Retry-After : attente, budget et décision de reprise
Décider d’une reprise API après 429 ou 503
Un délai d’attente répond à la question « quand retenter ? », pas à la question « peut-on répéter cette opération ? ». Avant toute reprise, il faut qualifier l’effet demandé, lire le contrat du fournisseur et borner le travail total. Un statut d’erreur ou une réponse perdue ne prouve pas qu’aucune tentative antérieure n’a produit d’effet.
Modèle pédagogique local, sans requête, minuteur, stockage ou écriture réelle. Il traite une seule décision après 429 ou 503, avec six en-têtes prédéfinis. Les dates sont lues à l’instant fictif du 22 octobre 2026 à 10:00:00 UTC, en supposant ici une horloge exacte. Ce n’est ni un parseur HTTP complet ni un client Stripe. Les anciennes formes HTTP-date, les décalages d’horloge, le transport et les politiques propres aux SDK sont hors calcul.
Douze lectures d’un champ Retry-After
Les durées sont des secondes. Une date absolue doit être interprétée avec une politique d’horloge explicite ; le calcul ci-dessous suppose l’horloge exacte annoncée. Une valeur passée est ramenée à zéro dans le modèle, sans autoriser une boucle immédiate. La syntaxe des entiers ne suffit pas à définir les limites numériques d’un client.
| Valeur illustrée | Lecture dans ce périmètre | Décision de lecture |
|---|---|---|
30 | Entier décimal non négatif : attendre 30 secondes après réception. | Le champ ne signifie pas « 30 millisecondes ». |
0005 | La syntaxe 1*DIGIT accepte ces chiffres : 5 secondes. | Ne pas confondre zéro initial et valeur octale. |
0 | Délai déclaré de zéro seconde. | La politique locale, les budgets et les droits de répétition restent à vérifier. |
Thu, 22 Oct 2026 10:00:45 GMT | Date HTTP à 45 secondes de l’instant fictif de réception. | Si l’horloge est incertaine, ne pas transformer cette différence en certitude. |
Thu, 22 Oct 2026 09:59:50 GMT | Date antérieure de 10 secondes ; attente serveur retenue à zéro dans ce modèle. | Une date passée n’impose pas une attente négative ni un rejeu illimité. |
Champ absent | Aucune attente serveur fournie. | Le client applique ici son délai local choisi, sans en faire une valeur par défaut normative. |
1.5 | 1.5 ne satisfait pas la syntaxe entière delay-seconds. | Ne pas arrondir silencieusement pour faire croire à un champ valide. |
-1 | -1 n’est pas un entier décimal non négatif de ce champ. | Ne pas lire cette valeur comme une autorisation spéciale. |
30s | L’unité s n’appartient pas à la syntaxe de delay-seconds. | L’unité est déjà la seconde ; 30s n’est pas la forme 30. |
30, 60 | Une liste de deux durées n’est pas une valeur Retry-After valide. | Ne pas couper toutes les virgules : une date HTTP valide contient elle-même une virgule. |
Valeur vide | Le champ est présent mais ne contient aucune des deux formes attendues. | Distinguer absence et valeur malformée dans les traces. |
9999999999999999999999 | La suite de chiffres satisfait la forme entière, mais dépasse les bornes numériques de ce modèle. | Classer le dépassement local sans prétendre que la RFC fixe la même borne ; ne pas tronquer pour retenter plus tôt. |
Comparer attente, budget restant et risque de répétition
Les cinq paramètres couvrent 144 combinaisons. Politique fictive : attente = maximum de l’attente serveur interprétable et du délai local déjà choisi ; réserver ensuite 10 secondes pour une tentative. Si le budget restant ne suffit pas, arrêter cette reprise interactive sans raccourcir l’attente serveur. La réserve n’est pas une durée mesurée. Le délai local choisi n’est pas un générateur de jitter.
Décision pédagogique :
La nature d’opération choisie et le budget permettent d’envisager une reprise dans ce modèle. Cela ne prouve ni son succès ni son autorisation sur un service réel.
- Attente serveur interprétable
- 30 s
- Attente retenue
- 30 s
- Réserve de tentative
- 10 s
- Attente + réserve
- 40 s
- Marge de budget
- 20 s
Champ absent ou invalide : le délai retenu provient ici de la politique locale. Une API réelle peut exiger une autre décision.
Huit cas à reproduire
| Situation fictive | Paramètres utiles | Décision et limite |
|---|---|---|
| 429, lecture et attente de 30 secondes | 429 · 30 secondes Lecture GET conforme Budget restant après réception : 60 s | Candidat à une reprise Avec 60 secondes restantes, 30 + 10 laisse 20 secondes de marge. |
| L’attente dépasse le budget | 429 · 30 secondes Lecture GET conforme Budget restant après réception : 20 s | Arrêter cette reprise Avec 20 secondes restantes, ne pas réduire 30 à une attente plus courte pour forcer une tentative. |
| Écriture au contrat inconnu | 503 · Date future : +45 secondes Écriture POST : contrat de reprise non vérifié Budget restant après réception : 60 s | Vérifier l’état métier Même une marge positive ne valide pas la répétition de POST. |
| Écriture avec contrat vérifié | 503 · Date future : +45 secondes Écriture POST : contrat de reprise vérifié Budget restant après réception : 60 s | Candidat à une reprise Le contrat vérifié est une hypothèse du modèle, pas un contrôle de votre fournisseur. |
| Valeur fractionnaire invalide | 503 · Valeur invalide : 1.5 Lecture GET conforme Budget restant après réception : 20 s | Candidat à une reprise Le repli à 5 secondes est un choix pédagogique local ; conserver l’erreur de lecture. |
| Champ absent, délai local long | 429 · Champ absent Lecture GET conforme Budget restant après réception : 60 s | Candidat à une reprise Le délai de 40 secondes vient du client et n’est pas une instruction reçue. |
| Date HTTP déjà passée | 503 · Date passée : −10 secondes Lecture GET conforme Budget restant après réception : 20 s | Candidat à une reprise Le modèle garde le délai local de 5 secondes ; la date passée ne déclenche aucun appel immédiat. |
| Zéro ne supprime pas le budget | 429 · 0 seconde Lecture GET conforme Budget restant après réception : 20 s | Arrêter cette reprise Le délai local de 40 secondes et la réserve dépassent les 20 secondes restantes. |
Cinq distinctions qui changent le comportement du client
| Repère | Ce qui est documenté | Limite pratique |
|---|---|---|
| 429 | La RFC 6585 décrit un excès de requêtes dans une période. Retry-After peut être présent ; la réponse 429 ne doit pas être stockée par un cache. | La RFC ne fixe ni l’identité comptée, ni la fenêtre, ni l’algorithme du fournisseur. |
| 503 | Retry-After peut indiquer la durée attendue d’indisponibilité du service. | Un même 5xx n’explique pas à lui seul la possibilité de rejouer une écriture. |
| Idempotence HTTP | PUT, DELETE et les méthodes sûres sont idempotentes au sens de l’effet demandé. | Les réponses et les journaux peuvent différer. POST demande un contrat supplémentaire pour une reprise maîtrisée. |
| Reprises à plusieurs étages | Les tentatives d’un client, d’un SDK et d’un proxy peuvent multiplier la charge. | Dans un exemple fictif de trois étages à trois tentatives totales chacun, une demande peut produire jusqu’à 3 × 3 × 3 = 27 appels au dernier étage. |
| Jitter et budget | AWS décrit la dispersion des reprises pour éviter la synchronisation des clients. | L’aléa ne rend pas une écriture idempotente et ne remplace ni délai global ni limite de tentatives. |
Cinq éléments à conserver dans une recette de reprise
- Méthode, route, version du contrat et identité logique de l’opération ; aucun secret dans la clé ou dans le journal.
- Statut et valeur brute du champ, instant de réception, interprétation et hypothèse d’horloge.
- Délai choisi, tentative courante, budget restant et étage qui pilote réellement les reprises.
- État métier connu ou inconnu, clé de reprise, contexte et paramètres associés ; trace d’un rapprochement si nécessaire.
- Résultat final vérifié et comportement utilisateur : attente compréhensible, saisie conservée et absence de bouton qui recrée involontairement l’opération.
Comparer les contrats d’idempotence →
Sources primaires et limites
Les RFC définissent les éléments HTTP cités. AWS décrit des choix de conception ; Stripe documente ses propres API. Les budgets, attentes locales, cas et schéma sont pédagogiques, sans mesure de votre service ni exécution d’une requête.
- IETF · RFC 9110 — Retry-After et idempotence HTTP · June 2022 · STD 97
§5.6.7; §9.2.2; §10.2.3; §15.6.4 - IETF · RFC 6585 — 429 Too Many Requests · April 2012 · Standards Track
§4 - AWS Builders’ Library · Timeouts, retries, and backoff with jitter · Published 2019-12-05; accessed 2026-10-22
Retries; jitter; timeout scope - Stripe · Idempotent requests · Documentation accessed 2026-10-22
API v1: saved results, parameters, key pruning, execution boundary - Stripe · API v2 overview — Idempotency · Documentation accessed 2026-10-22
POST/DELETE; same API and account/sandbox; 30-day replay window - Stripe · Advanced error handling · Documentation accessed 2026-10-22
Stripe-Should-Retry; status codes; idempotency
Références relues le
GraphQL : erreurs, listes et données partielles
Coût GraphQL et résultat partiel : deux contrôles à tester
Une requête autorisée peut rester trop coûteuse ; une réponse partielle ne donne aucune mesure de sa consommation.
- Comparer data absente, data partielle et data: null.
- Conserver le chemin original, même si un parent devient null.
- Tester les droits, les quotas et les états d’interface séparément.
Explorer les réponses GraphQL et leur nullabilité →
GraphQL Specification · September 2025 · Published edition · September 2025
Références officielles
Date de consultation des références : . La méthode et la fiche de travail proposent des contrôles à adapter à votre contexte ; elles ne constituent pas une certification.
- IETF — RFC 6585, HTTP 429
- IETF — RFC 9110, Retry-After
- AWS — Timeouts, retries, and backoff with jitter
- IETF — RFC 9110, Retry-After
- GraphQL Specification · September 2025
- IETF · RFC 9110 — Retry-After et idempotence HTTP
- IETF · RFC 6585 — 429 Too Many Requests
- Stripe · Idempotent requests
- Stripe · API v2 overview — Idempotency
- Stripe · Advanced error handling
