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

Archives de renseignement avec dossiers et cartes, sans personne Illustration éditoriale générée par IA

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

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

PolitiqueCalcul ou horaireCe que cela change
Reprise simultanée20 × 1 = 20 @ +30 sAttendre 30 secondes respecte le délai, mais les 20 requêtes repartent au même instant : la rafale peut revenir.
Reprise répartie4 × 5 = 20 @ +30…+34 sQuatre 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 secondes25 s < 30 s → 0Si 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 maximal20 × (1 + 3) = 80Si 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

  1. Relevez quota, portée et budget de reprise.
  2. Épuisez le quota uniquement dans un test autorisé.
  3. 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.
  4. Dans une simulation sans charge externe, comptez les tentatives de quatre couches limitées chacune à trois appels totaux.
  5. Faites expirer une tâche fictive en file et vérifiez qu’elle ne démarre pas comme nouvelle opération.
  6. Réintroduisez progressivement les travaux autorisés après une panne simulée et conservez appels, échéances et résultats métier uniques.

AWS — Timeouts, retries, and backoff with jitter

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.

ChampInformation à consigner
LimiteUnité, fenêtre, identité et route
DépassementRéponse, délai et message utilisateur
RepriseBudget d’essais, doublons et arrêt
PreuveCharge 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écanismeUtilitéPoint de vigilance
Limite de débitEncadrer les arrivées sur une fenêtrePeut laisser passer des opérations lentes
ConcurrenceLimiter les traitements simultanésNe borne pas seule l’usage mensuel
Quota de consommationEncadrer un budget cumuléDéfinir renouvellement et unité facturée

Indicateurs de pilotage

IndicateurCe qu’il mesurePremière action
RefusRequêtes refusées par route et identitéSéparer abus et clients légitimes
Reprises utilesTentatives conduisant à un résultat uniqueRéduire boucles et doublons
Amplification des appelsAppels à la dépendance / opérations métier initiales sur la même fenêtreSéparer tentatives totales, reprises et sous-appels prévus
Travaux périmés admisTâches commencées après leur échéance utileMesurer 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.

Laboratoire réseau fictif sans personne, passerelles sur un établi sombre éclairé en ambre. Illustration éditoriale générée par IA
Laboratoire réseau conceptuel sans personne, généré pour la collection éditoriale. Il ne représente ni une infrastructure réelle ni un test de débit.

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.

Douze lectures d’un champ Retry-After
Valeur illustréeLecture dans ce périmètreDécision de lecture
30Entier décimal non négatif : attendre 30 secondes après réception.Le champ ne signifie pas « 30 millisecondes ».
0005La syntaxe 1*DIGIT accepte ces chiffres : 5 secondes.Ne pas confondre zéro initial et valeur octale.
0Dé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 GMTDate 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 GMTDate 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 absentAucune attente serveur fournie.Le client applique ici son délai local choisi, sans en faire une valeur par défaut normative.
1.51.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.
30sL’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, 60Une 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 videLe champ est présent mais ne contient aucune des deux formes attendues.Distinguer absence et valeur malformée dans les traces.
9999999999999999999999La 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 : Candidat à une reprise

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

Huit cas à reproduire

Huit cas à reproduire
Situation fictiveParamètres utilesDécision et limite
429, lecture et attente de 30 secondes429 · 30 secondes

Lecture GET conforme

Budget restant après réception : 60 s
Délai local déjà choisi : 5 s

Candidat à une reprise

Avec 60 secondes restantes, 30 + 10 laisse 20 secondes de marge.

L’attente dépasse le budget429 · 30 secondes

Lecture GET conforme

Budget restant après réception : 20 s
Délai local déjà choisi : 5 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 inconnu503 · Date future : +45 secondes

Écriture POST : contrat de reprise non vérifié

Budget restant après réception : 60 s
Délai local déjà choisi : 5 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
Délai local déjà choisi : 5 s

Candidat à une reprise

Le contrat vérifié est une hypothèse du modèle, pas un contrôle de votre fournisseur.

Valeur fractionnaire invalide503 · Valeur invalide : 1.5

Lecture GET conforme

Budget restant après réception : 20 s
Délai local déjà choisi : 5 s

Candidat à une reprise

Le repli à 5 secondes est un choix pédagogique local ; conserver l’erreur de lecture.

Champ absent, délai local long429 · Champ absent

Lecture GET conforme

Budget restant après réception : 60 s
Délai local déjà choisi : 40 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ée503 · Date passée : −10 secondes

Lecture GET conforme

Budget restant après réception : 20 s
Délai local déjà choisi : 5 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 budget429 · 0 seconde

Lecture GET conforme

Budget restant après réception : 20 s
Délai local déjà choisi : 40 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

Cinq distinctions qui changent le comportement du client
RepèreCe qui est documentéLimite pratique
429La 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.
503Retry-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 HTTPPUT, 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 étagesLes 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 budgetAWS 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.

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.