Pourquoi le 429 Retry-After manque dans la plupart des API de réseaux sociaux

Que signifie 429 Retry-After ?

Dans le protocole HTTP, une réponse 429 Retry-After, c'est un serveur qui dit à un client qu'il a envoyé trop de requêtes et, en option, combien de temps attendre avant la suivante. Les deux moitiés viennent de deux spécifications différentes.

La RFC 6585 définit le code de statut : « The 429 status code indicates that the user has sent too many requests in a given amount of time ("rate limiting"). » Elle rend ensuite l'en-tête facultatif : « The response representations SHOULD include details explaining the condition, and MAY include a Retry-After header indicating how long to wait before making a new request. »

La RFC 9110 définit l'en-tête lui-même, dans sa section 10.2.3 : « Servers send the "Retry-After" header field to indicate how long the user agent ought to wait before making a follow-up request. » La section décrit ensuite ce que signifie l'en-tête sur un 503 et sur une redirection 3xx. Elle ne mentionne jamais le 429. Le lien entre le code de statut et l'en-tête se trouve entièrement dans la RFC 6585, et il y est un MAY.

La RFC 6585 laisse aussi le décompte au serveur : « Note that this specification does not define how the origin server identifies the user, nor how it counts requests. » Cette seule phrase explique pourquoi chaque plateforme ci-dessous se comporte différemment. La norme leur donne un code de statut et un en-tête facultatif, et rien d'autre.

Si un cache se trouve devant votre client d'API, la RFC 6585 lui impose une règle de plus : « Responses with the 429 status code MUST NOT be stored by a cache. »

Comment interpréter une valeur Retry-After ?

La RFC 9110 autorise deux formes : « The Retry-After field value can be either an HTTP-date or a number of seconds to delay after receiving the response. »

Retry-After: Fri, 31 Dec 1999 23:59:59 GMT
Retry-After: 120

La forme en secondes est « a non-negative decimal integer, representing time in seconds », et la RFC précise que le second exemple correspond à un délai de 2 minutes. Un parseur doit gérer les deux. Essayez d'abord l'entier, puis rabattez-vous sur une date :

from email.utils import parsedate_to_datetime
from datetime import datetime, timezone
 
def retry_after_seconds(value):
    if value.strip().isdigit():
        return int(value)
    when = parsedate_to_datetime(value)
    return max(0, (when - datetime.now(timezone.utc)).total_seconds())

Quelles API de réseaux sociaux envoient un en-tête Retry-After ?

Aucune des cinq, à en croire leur propre documentation. Chacune signale une limite de débit à sa façon, et deux d'entre elles n'utilisent pas toujours le 429.

Bluesky et Pinterest ont leurs propres systèmes d'en-têtes, présentés dans le détail des limites de débit de l'API Bluesky et la référence des limites de débit de l'API Pinterest.

Comment l'API X signale-t-elle une limite de débit ?

Avec un 429 et trois en-têtes sur chaque réponse. La page des limites de débit de X : « Exceeding limits results in a 429 error until the window resets. » Elle documente x-rate-limit-limit comme « Maximum requests allowed », x-rate-limit-remaining comme « Requests remaining in window » et x-rate-limit-reset comme « Unix timestamp when window resets. »

x-rate-limit-reset est le champ à utiliser, et c'est une heure absolue, pas un délai. La valeur d'exemple de X est 1705420800. Passez-la telle quelle en secondes à un appel de mise en veille et le worker dort environ 54 ans, donc soustrayez d'abord l'heure Unix courante. La stratégie de reprise de X tient en trois étapes : « Check x-rate-limit-reset for when the window resets », « Wait until that time before retrying », « Use exponential backoff if needed. » Son code d'exemple attend max(reset_time - time.time(), 60), donc jamais moins d'une minute.

X documente deux corps différents pour la même situation. La page des limites de débit montre un 429 qui renvoie {"errors": [{"code": 88, "message": "Rate limit exceeded"}]}. La page des codes de réponse décrit les erreurs comme des objets avec type, title et detail, et liste un type .../rate-limit-exceeded. Basez-vous sur le statut HTTP, et traitez les deux formes de corps comme une limite de débit.

La même page ajoute un piège. X définit le 429 comme « Rate limit or usage cap exceeded », et liste un type d'erreur distinct, .../usage-capped. Un 429 causé par un plafond d'usage ne se lève pas quand x-rate-limit-reset est passé. Vérifiez le type d'erreur avant de programmer une nouvelle tentative à l'heure de réinitialisation.

Comment Meta signale-t-il une limite de débit ?

Avec des codes d'erreur dans le corps JSON. La référence de Meta sur la limitation de débit et son guide de gestion des erreurs les listent, et aucune des deux pages n'indique quel statut HTTP les accompagne.

Meta se contredit sur la marche à suivre. Le guide de gestion des erreurs dit, pour 4 comme pour 17 : « Temporary issue due to throttling. Wait and retry the operation, or examine your API request volume. » La référence sur la limitation de débit dit : « When the limit has been reached, stop making API calls. Continuing to make calls will continue to increase your call count, which will increase the time before calls will be successful again. » Suivez la plus stricte, car retenter sous les règles de Meta allonge le blocage.

Le signal temporel de Meta dépend de celui de ses deux systèmes de limitation qui vous a arrêté. L'en-tête business use case porte estimated_time_to_regain_access, défini comme « Time, in minutes, until calls will not longer be throttled. » Attention à l'unité : Retry-After compte en secondes, ce champ compte en minutes. L'en-tête au niveau de l'application n'a aucun champ temporel, ce que le détail de l'en-tête x-app-usage couvre en profondeur.

Comment LinkedIn et TikTok signalent-ils une limite de débit ?

Tous deux renvoient un simple 429 et ne documentent aucun en-tête temporel.

La page de LinkedIn sur la limitation de débit : « Rate limited requests will receive a 429 response. » Sa page de gestion des erreurs donne le message : « Resource level throttle limit for calls to this resource is reached. » LinkedIn ne publie pas non plus les limites elles-mêmes : « Standard rate limits are not published in documentation. » Vous les trouvez dans l'onglet Analytics du Developer Portal, et seulement pour les endpoints que vous avez appelés au moins une fois ce jour-là, en UTC.

Le calendrier remplace l'en-tête pour le calage. LinkedIn indique que les limites couvrent « a 24 hour period » et « reset at midnight UTC every day. » Après un 429 de LinkedIn causé par votre propre volume, la première nouvelle tentative utile a lieu au prochain 00:00 UTC. LinkedIn envoie aussi des 429 pour une raison qui ne vient pas de vous : « In rare cases, LinkedIn may also return a 429 response as part of infrastructure protection. API service will return to normal automatically. » Rien dans la réponse ne permet de distinguer les deux cas.

La page de TikTok sur les limites de débit : « Request rate calculation is based on a one minute sliding window. If the number of requests exceeds the threshold, new requests will be throttled and a response will be returned with HTTP status 429 and error code rate_limit_exceeded. » La page liste 600 requêtes pour chacun de /v2/user/info/, /v2/video/query/ et /v2/video/list/. L'endpoint de publication est bien plus serré. La référence de la Content Posting API dit de /v2/post/publish/video/init/ : « Each user access_token is limited to 6 requests per minute. »

Le plafond quotidien de publication de TikTok n'est pas un 429. C'est un 403 avec spam_risk_too_many_posts, décrit comme « The daily post cap from the API is reached for the current user. » Une boucle de nouvelles tentatives basée sur le 429 ne le verra jamais, et une boucle qui retente chaque 4xx le martèlera pour rien.

Comment YouTube signale-t-il une erreur de quota ?

Surtout avec un 403. La référence des erreurs de YouTube liste quotaExceeded (403) : « The request cannot be completed because you have exceeded your quota. » C'est l'erreur que produit un quota quotidien épuisé, et ce n'est pas un 429.

La présentation de YouTube indique le budget par défaut : « Projects that enable the YouTube Data API have a default quota allocation of 100 search.list calls, 100 videos.insert calls, and 10,000 units per day combined for all other endpoints. » Elle note aussi que « All API requests, including invalid requests, incur at least a one-point quota cost », donc les tentatives ratées dépensent quand même du quota.

Le seul 429 de la référence des erreurs de YouTube concerne les miniatures : tooManyRequests (429) uploadRateLimitExceeded, « The channel has uploaded too many thumbnails recently. Please try the request again later. » Le plafond quotidien de mises en ligne est encore un troisième statut, badRequest (400) uploadLimitExceeded, avec une description sans ambiguïté : « This is a YouTube platform restriction and is entirely separate from your Google Cloud project's API quota. » Un quotaExceeded ne se retente pas le jour même. Relever le plafond est une démarche administrative, détaillée dans ce qu'implique une extension de quota de l'API YouTube.

Que doit faire une politique de nouvelles tentatives quand Retry-After manque ?

Lire le signal propre à la plateforme, et séparer les plafonds des limites de débit avant de retenter quoi que ce soit.

Si une réponse porte bien Retry-After, respectez-le. Sinon, prenez l'attente fournie par la plateforme : x-rate-limit-reset moins l'heure courante pour X, estimated_time_to_regain_access en minutes pour les limites business use case de Meta, le prochain minuit UTC pour LinkedIn, et au moins une minute pour la fenêtre glissante de TikTok. Pour les erreurs de Meta au niveau de l'application, arrêtez la file et vérifiez X-App-Usage avant de reprendre.

Ensuite, orientez à part les erreurs qui ressemblent à des limites de débit sans en être : le spam_risk_too_many_posts de TikTok, les quotaExceeded et uploadLimitExceeded de YouTube, et le plafond d'usage de X. Ce sont des plafonds quotidiens, et un backoff mesuré en secondes n'en lèvera aucun.

Questions fréquentes

L'en-tête Retry-After est-il obligatoire sur une réponse 429 ?

Non. La RFC 6585 dit qu'une réponse 429 « MAY include a Retry-After header indicating how long to wait before making a new request. » Seule l'explication de la situation est un SHOULD.

Quels formats un en-tête Retry-After peut-il utiliser ?

La RFC 9110 autorise une date HTTP, comme Fri, 31 Dec 1999 23:59:59 GMT, ou un nombre entier positif ou nul de secondes, comme 120. Les parseurs doivent gérer les deux.

L'API X envoie-t-elle Retry-After sur un 429 ?

Les pages de X sur les limites de débit et les erreurs ne le documentent pas. Elles vous renvoient à x-rate-limit-reset, un timestamp Unix qui marque la réinitialisation de la fenêtre, et le code d'exemple de X attend au moins 60 secondes.

Quel statut HTTP la Graph API de Facebook renvoie-t-elle pour une limite de débit ?

Meta ne le précise ni dans la référence sur la limitation de débit ni dans le guide de gestion des erreurs. Les deux identifient les limites de débit par le champ code du corps d'erreur JSON : 4, 17, 32, 613, ou 80001 pour les limites business use case des Pages.

La YouTube Data API renvoie-t-elle un 429 quand le quota est épuisé ?

Non. Un quota épuisé renvoie un 403 avec la raison quotaExceeded. Le seul 429 de la référence des erreurs de YouTube est uploadRateLimitExceeded, sur les mises en ligne de miniatures.

Quand une limite de débit de l'API LinkedIn se réinitialise-t-elle ?

À minuit UTC. La page de LinkedIn sur la limitation de débit dit que les limites couvrent une période de 24 heures et « reset at midnight UTC every day. » LinkedIn ne documente aucun en-tête de réinitialisation, alors calculez l'attente à partir de l'horloge.

Comment transformer x-rate-limit-reset en durée d'attente ?

Soustrayez l'heure Unix actuelle, car c'est un horodatage absolu et non un délai. La valeur d'exemple de X est 1705420800 ; passée en secondes à un appel sleep, elle endort le worker pendant environ 54 ans. Le code d'exemple de X attend max(reset_time - time.time(), 60), donc jamais moins d'une minute.

Faut-il réessayer une erreur quotaExceeded de YouTube ?

Pas le même jour. Un quotaExceeded (403) signifie que le quota quotidien est épuisé, et chaque requête, même invalide, coûte au moins un point, donc les nouvelles tentatives ne font que consommer du quota. Relever le plafond passe par une démarche administrative.

Que renvoie TikTok quand le plafond quotidien de publications est atteint ?

Un 403 avec le code d'erreur spam_risk_too_many_posts, décrit ainsi : "Le plafond quotidien de publications de l'API est atteint pour l'utilisateur actuel." Ce n'est pas un 429, donc une boucle de retry fondée sur le 429 ne le voit jamais. Réessayer tous les 4xx martèle l'endpoint pour rien.

Faut-il continuer à réessayer quand Meta renvoie le code d'erreur 4 ou 17 ?

Arrêtez les appels. La référence de rate limiting de Meta prévient que continuer à appeler augmente le compteur d'appels, ce qui allonge le délai avant que les appels réussissent à nouveau. Le guide de gestion des erreurs conseille d'attendre puis de réessayer ; les deux pages se contredisent, et la règle la plus stricte est la plus sûre.