En-tête Retry-After : durée d’attente avant de réessayer

Retry-After est un en-tête de réponse HTTP qui indique à votre application combien de temps attendre avant d’envoyer la requête suivante. La valeur est un nombre de secondes ou une date HTTP. Quand une API l’envoie, il s’agit de la réponse la plus fiable à « quand puis-je réessayer ? » car elle provient du serveur qui a rejeté votre demande. Pour plus d’informations, consultez RFC 9110, section 10.2.3.

À quoi ressemble Retry-After

L’en-tête existe en 2 formats. Votre application doit gérer les deux.

Format Example Ce que cela signifie
Seconds Retry-After: 120 Attendez 120 secondes (2 minutes) à partir du moment où vous avez obtenu la réponse. La valeur est un nombre entier non négatif.
date HTTP Retry-After: Fri, 31 Dec 1999 23:59:59 GMT N’envoyez pas à nouveau la requête avant cette heure. L’heure est toujours en GMT.

Les serveurs envoient Retry-After avec ces codes d’état :

Status Que signifie Retry-After Source
429 Too Many Requests Délai d’attente avant d’envoyer une nouvelle demande. Le serveur peut l’inclure. RFC 6585, section 4
503 Service Unavailable Durée pendant laquelle le service est censé être indisponible. Le serveur peut l’inclure. RFC 9110, section 15.6.4
413 Content Too Large Si la condition est temporaire, le serveur doit indiquer après combien de temps elle prend fin. RFC 9110, section 15.5.14
N’importe quelle 3xx redirection Délai minimal à attendre avant de suivre la redirection. RFC 9110, section 10.2.3

L’en-tête est facultatif. Certaines API utilisent plutôt leurs propres en-têtes. Par exemple, GitHub vous indique quand votre limite est réinitialisée avec x-ratelimit-reset. Pour plus d’informations, consultez limite de débit de l’API GitHub dépassée.

Comment traiter Retry-After

  1. Lisez les deux formats. Si la valeur est un nombre, il s’agit de secondes. Sinon, analysez-la sous la forme d’une date et soustrayez l’heure actuelle. Si la date est déjà passée, vous pouvez réessayer immédiatement.
  2. Attendez au moins aussi longtemps que l’en-tête l’indique. Réessayer plus tôt permet généralement d’obtenir un autre 429 ou 503. Certaines API continuent de compter vos demandes pendant qu’elles vous limitent, de sorte que des réessais trop précoces peuvent rendre l’attente plus longue. Par exemple, consultez conseils relatifs à la limitation du débit de Microsoft Graph.
  3. Utilisez une temporisation avec gigue en repli lorsque l’en-tête est manquant. Doublez l’attente après chaque tentative ayant échoué, ajoutez une quantité aléatoire afin que de nombreux clients ne réessayent pas en même temps, et plafonnez l’attente.
  4. Limitez vos tentatives. Après quelques tentatives, retournez l’erreur à l’appelant.
  5. Vérifiez si une nouvelle tentative peut résoudre le problème. Certaines API retournent 429 lorsque vos crédits sont épuisés ou que votre limite de dépense est atteinte. L’attente ne les corrigera pas. Pour obtenir un exemple, consultez OpenAI insufficient_quota et credit_balance_exhausted.
function retryDelayMs(response, attempt) {
  const value = response.headers.get('retry-after');
  if (value) {
    const seconds = Number(value);
    const ms = Number.isNaN(seconds) ? Date.parse(value) - Date.now() : seconds * 1000;
    if (!Number.isNaN(ms)) {
      return Math.max(ms, 0);
    }
  }
  // No usable header: exponential backoff with jitter, capped at 30 seconds
  return Math.random() * Math.min(30_000, 1_000 * 2 ** attempt);
}

De nombreux kits SDK gèrent Retry-After pour vous, mais uniquement jusqu’à épuisement des tentatives. Votre code rencontre alors cette erreur.

SDK Ce qu’il fait par défaut
.NET gestionnaire standard de résilience Réessaie les réponses 408, 429 et 5xx jusqu’à 3 fois avec un backoff exponentiel et de la gigue. Il utilise Retry-After pour le délai, car la valeur par défaut de ShouldRetryAfterHeader est true.
Kits de développement logiciel (SDK) Microsoft Graph Utilisez Retry-After lorsqu’il est présent, et repliez-vous sur un backoff exponentiel quand ce n’est pas le cas. Les requêtes à l’intérieur d’un lot JSON ne sont pas retentées automatiquement.
Kit de développement logiciel (SDK) Python OpenAI Retente les erreurs de connexion et 408, 409, 429et 5xx les réponses 2 fois avec une interruption exponentielle courte. Définissez max_retries pour le modifier.

Consultez la documentation de votre SDK pour connaître la stratégie exacte et testez ce qui se passe après l’échec de la dernière tentative.

Comment tester que votre application gère Retry-After

Vous obtenez rarement un Retry-After pendant le développement, et quand cela arrive, vous ne pouvez pas contrôler sa valeur. Ainsi, la façon dont vous testez cela détermine si vous trouvez les bogues avant que vos utilisateurs ne le fassent.

Approach Ce que vous trouvez Ce qui vous manque
Attendre la mise en production Échecs réels Tout, jusqu’à ce qu’un utilisateur clique dessus
Simuler l’API dans vos tests ou laisser votre agent de codage écrire la simulation Si votre code analyse l’en-tête Vérifiez si votre client HTTP réel ou votre SDK attend suffisamment longtemps, et ce que l’API envoie vraiment. Votre application a également besoin d’un commutateur réservé aux tests pour atteindre le mock.
Appelez l’API réelle jusqu’à ce qu’elle vous limite Comportement réel Vous ne pouvez pas déclencher une réponse avec limitation de débit à la demande, et vous consommez votre quota réel
Interceptez le trafic réel de votre application et retourner des réponses bridées à la demande Si votre SDK réel et votre stratégie de réessai attendent aussi longtemps que l’indique l’en-tête Rien dans votre application ne change, de sorte que cela ne teste donc pas votre code de manière isolée. Conservez vos tests unitaires pour cela.

Essayez-le dans votre application

Dev Proxy intercepte les demandes de votre application aux API que vous choisissez et retourne 429 des réponses avec un Retry-After en-tête, tandis que votre application continue d’appeler les URL réelles. RetryAfterPlugin mémorise à quel moment chaque requête soumise à une limitation de débit peut être retentée. Si votre application appelle la même URL avant ce moment-là, Dev Proxy le signale et applique de nouveau une limitation à la requête. Le plug-in effectue uniquement le suivi des réponses 429.

Dans votre fichier d’erreurs pour le GenericRandomErrorPlugin, définissez la valeur Retry-After d’une réponse 429 sur @dynamic, et Dev Proxy renseigne le nombre de secondes et en assure le suivi pour vous.

Pour l’essayer, téléchargez un préréglage qui utilise les deux plug-ins et démarrez Dev Proxy avec celui-ci :

devproxy config get openai-throttling
devproxy --config-file "~dataFolder/configs/openai-throttling/.devproxy/devproxyrc.json"

Exécutez ensuite votre application comme d’habitude et regardez ce qu’elle fait. Pour installer Dev Proxy, consultez Configurer Dev Proxy.

Étapes suivantes

Tester si mon application gère correctement la limitation de requêtes

Voir aussi

  • Dernière mise à jour :