Warum 429 Retry-After in den meisten Social-Media-APIs fehlt

Was bedeutet 429 Retry-After?

Eine Antwort mit 429 Retry-After ist ein Server, der einem Client sagt, dass er zu viele Anfragen gesendet hat, und optional, wie lange er bis zur nächsten warten soll. Die beiden Hälften stammen aus zwei verschiedenen Spezifikationen.

RFC 6585 definiert den Statuscode: „The 429 status code indicates that the user has sent too many requests in a given amount of time (‚rate limiting‘).“ Danach macht es den Header optional: „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.“

RFC 9110 definiert den Header selbst, in Abschnitt 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.“ Der Abschnitt beschreibt anschließend, was der Header bei einem 503 und bei einer 3xx-Weiterleitung bedeutet. 429 erwähnt er nie. Die Verbindung zwischen Statuscode und Header steht ausschließlich in RFC 6585, und dort ist sie ein MAY.

RFC 6585 überlässt auch das Zählen dem Server: „Note that this specification does not define how the origin server identifies the user, nor how it counts requests.“ Dieser eine Satz erklärt, warum sich jede der folgenden Plattformen anders verhält. Der Standard gibt ihnen einen Statuscode und einen optionalen Header, sonst nichts.

Wenn vor deinem API-Client ein Cache sitzt, hat RFC 6585 noch eine Regel dafür: „Responses with the 429 status code MUST NOT be stored by a cache.“

Wie parst man einen Retry-After-Wert?

RFC 9110 erlaubt zwei Formen: „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

Die Sekundenform ist „a non-negative decimal integer, representing time in seconds“, und der RFC stellt klar, dass das zweite Beispiel eine Verzögerung von 2 Minuten bedeutet. Ein Parser muss beide Formen beherrschen. Versuche zuerst den Integer, dann greife auf ein Datum zurück:

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())

Welche Social-Media-APIs senden einen Retry-After-Header?

Keine der fünf, jedenfalls laut ihrer eigenen Dokumentation. Jede signalisiert ein Rate Limit auf ihre eigene Weise, und zwei davon verwenden nicht immer 429.

Bluesky und Pinterest haben eigene Header-Schemata, behandelt in der Aufschlüsselung des Bluesky-API-Rate-Limits und der Referenz zum Pinterest-API-Rate-Limit.

Wie signalisiert die X API ein Rate Limit?

Mit einem 429 und drei Headern in jeder Antwort. Die Seite zu den Rate Limits von X: „Exceeding limits results in a 429 error until the window resets.“ Sie dokumentiert x-rate-limit-limit als „Maximum requests allowed“, x-rate-limit-remaining als „Requests remaining in window“ und x-rate-limit-reset als „Unix timestamp when window resets.“

x-rate-limit-reset ist das Feld, das du verwenden solltest, und es ist ein absoluter Zeitpunkt, keine Verzögerung. Der Beispielwert von X ist 1705420800. Übergib das einem Sleep-Aufruf als Sekunden, und der Worker schläft etwa 54 Jahre, also zieh zuerst die aktuelle Unix-Zeit ab. Die Wiederherstellungsstrategie von X hat drei Schritte: „Check x-rate-limit-reset for when the window resets“, „Wait until that time before retrying“, „Use exponential backoff if needed.“ Der Beispielcode wartet max(reset_time - time.time(), 60), also nie weniger als eine Minute.

X dokumentiert zwei verschiedene Bodies für dieselbe Bedingung. Die Rate-Limits-Seite zeigt einen 429, der {"errors": [{"code": 88, "message": "Rate limit exceeded"}]} zurückgibt. Die Seite zu den Antwortcodes beschreibt Fehler als Objekte mit type, title und detail und führt einen Typ .../rate-limit-exceeded auf. Prüfe den HTTP-Status und behandle beide Body-Formen als Rate Limit.

Dieselbe Seite hat noch einen Haken. X definiert 429 als „Rate limit or usage cap exceeded“ und führt einen separaten Fehlertyp .../usage-capped auf. Ein 429 wegen einer Nutzungsobergrenze verschwindet nicht, wenn x-rate-limit-reset verstrichen ist. Prüfe den Fehlertyp, bevor du einen Retry zum Reset-Zeitpunkt einplanst.

Wie signalisiert Meta ein Rate Limit?

Mit Fehlercodes im JSON-Body. Metas Rate-Limiting-Referenz und der Leitfaden zur Fehlerbehandlung listen sie auf, und keine der beiden Seiten sagt, welcher HTTP-Status dazugehört.

Meta widerspricht sich dabei, was als Nächstes zu tun ist. Der Leitfaden zur Fehlerbehandlung sagt für 4 und 17: „Temporary issue due to throttling. Wait and retry the operation, or examine your API request volume.“ Die Rate-Limiting-Referenz sagt: „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.“ Folge der strengeren Aussage, denn nach Metas Regeln verlängern Retries die Sperre.

Metas Zeitsignal hängt davon ab, welches seiner beiden Rate-Limit-Systeme dich erwischt hat. Der Business-Use-Case-Header enthält estimated_time_to_regain_access, definiert als „Time, in minutes, until calls will not longer be throttled.“ Achte auf die Einheit: Retry-After zählt in Sekunden, dieses Feld in Minuten. Der Header auf App-Ebene hat überhaupt kein Zeitfeld, was die Aufschlüsselung des Headers x-app-usage im Detail behandelt.

Wie signalisieren LinkedIn und TikTok ein Rate Limit?

Beide geben einen schlichten 429 zurück und dokumentieren keine Zeit-Header.

Die Rate-Limiting-Seite von LinkedIn: „Rate limited requests will receive a 429 response.“ Die Seite zur Fehlerbehandlung nennt die Meldung: „Resource level throttle limit for calls to this resource is reached.“ Die Limits selbst veröffentlicht LinkedIn auch nicht: „Standard rate limits are not published in documentation.“ Du findest sie im Analytics-Tab des Developer Portal, und nur für Endpunkte, die du an diesem UTC-Tag mindestens einmal aufgerufen hast.

Das Timing kommt aus dem Kalender statt aus einem Header. LinkedIn gibt an, dass Limits „a 24 hour period“ umfassen und „reset at midnight UTC every day.“ Nach einem LinkedIn-429 wegen deines eigenen Volumens ist der früheste sinnvolle Retry das nächste 00:00 UTC. LinkedIn sendet 429 auch aus einem Grund, der nicht bei dir liegt: „In rare cases, LinkedIn may also return a 429 response as part of infrastructure protection. API service will return to normal automatically.“ Nichts in der Antwort unterscheidet die beiden Fälle.

Die Rate-Limits-Seite von TikTok: „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.“ Die Seite nennt 600 Anfragen für jeden der Endpunkte /v2/user/info/, /v2/video/query/ und /v2/video/list/. Der Veröffentlichungsendpunkt ist deutlich enger. Die Referenz der Content Posting API sagt über /v2/post/publish/video/init/: „Each user access_token is limited to 6 requests per minute.“

TikToks tägliche Postingobergrenze ist kein 429. Sie ist ein 403 mit spam_risk_too_many_posts, beschrieben als „The daily post cap from the API is reached for the current user.“ Eine Retry-Schleife, die auf 429 reagiert, sieht ihn nie, und eine Retry-Schleife, die jeden 4xx wiederholt, hämmert umsonst dagegen.

Wie signalisiert YouTube einen Kontingentfehler?

Meistens mit einem 403. YouTubes Fehlerreferenz führt quotaExceeded (403) auf: „The request cannot be completed because you have exceeded your quota.“ Das ist der Fehler, den ein aufgebrauchtes Tageskontingent erzeugt, und er ist kein 429.

YouTubes Übersicht nennt das Standardbudget: „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.“ Sie merkt außerdem an, dass „All API requests, including invalid requests, incur at least a one-point quota cost“, fehlgeschlagene Retries verbrauchen also trotzdem Kontingent.

Der einzige 429 in YouTubes Fehlerreferenz gehört zu Thumbnails: tooManyRequests (429) uploadRateLimitExceeded, „The channel has uploaded too many thumbnails recently. Please try the request again later.“ Die tägliche Upload-Obergrenze ist wiederum ein dritter Status, badRequest (400) uploadLimitExceeded, mit einer deutlichen Beschreibung: „This is a YouTube platform restriction and is entirely separate from your Google Cloud project's API quota.“ Ein quotaExceeded lässt sich am selben Tag nicht wiederholen. Die Obergrenze anzuheben ist ein Papierkram-Prozess, beschrieben in was eine Kontingenterweiterung der YouTube API umfasst.

Was sollte eine Retry-Policy tun, wenn Retry-After fehlt?

Das eigene Signal der Plattform lesen und Obergrenzen von Rate Limits trennen, bevor irgendetwas wiederholt wird.

Wenn eine Antwort Retry-After enthält, halte dich daran. Andernfalls nimm die Wartezeit von der Plattform: x-rate-limit-reset minus jetzt bei X, estimated_time_to_regain_access in Minuten bei Metas Business-Use-Case-Limits, die nächste Mitternacht UTC bei LinkedIn und mindestens eine Minute beim gleitenden Fenster von TikTok. Bei Metas Fehlern auf App-Ebene stoppe die Warteschlange und prüfe X-App-Usage, bevor du fortfährst.

Leite dann die Fehler um, die wie Rate Limits aussehen, aber keine sind: TikToks spam_risk_too_many_posts, YouTubes quotaExceeded und uploadLimitExceeded sowie die Nutzungsobergrenze von X. Das sind Tagesobergrenzen, und ein Backoff im Sekundenbereich löst keine davon.

Häufig gestellte Fragen

Ist der Retry-After-Header bei einer 429-Antwort Pflicht?

Nein. RFC 6585 sagt, eine 429-Antwort „MAY include a Retry-After header indicating how long to wait before making a new request.“ Nur die Erklärung der Bedingung ist ein SHOULD.

Welche Formate kann ein Retry-After-Header verwenden?

RFC 9110 erlaubt ein HTTP-Datum wie Fri, 31 Dec 1999 23:59:59 GMT oder eine nicht negative ganze Zahl von Sekunden wie 120. Parser müssen beides beherrschen.

Sendet die X API bei einem 429 ein Retry-After?

Die Seiten zu Rate Limits und Fehlern von X dokumentieren es nicht. Sie verweisen auf x-rate-limit-reset, einen Unix-Zeitstempel, der das Zurücksetzen des Fensters markiert, und der Beispielcode von X wartet mindestens 60 Sekunden.

Welchen HTTP-Status gibt die Facebook Graph API bei einem Rate Limit zurück?

Meta nennt ihn weder in der Rate-Limiting-Referenz noch im Leitfaden zur Fehlerbehandlung. Beide erkennen Rate Limits am Feld code im JSON-Fehler-Body: 4, 17, 32, 613 oder 80001 für Business-Use-Case-Limits bei Seiten.

Gibt die YouTube Data API 429 zurück, wenn das Kontingent aufgebraucht ist?

Nein. Ein aufgebrauchtes Kontingent liefert 403 mit dem Grund quotaExceeded. Der einzige 429 in YouTubes Fehlerreferenz ist uploadRateLimitExceeded bei Thumbnail-Uploads.

Wann wird ein Rate Limit der LinkedIn API zurückgesetzt?

Um Mitternacht UTC. Die Rate-Limiting-Seite von LinkedIn sagt, dass Limits einen Zeitraum von 24 Stunden umfassen und „reset at midnight UTC every day.“ LinkedIn dokumentiert keinen Reset-Header, also berechne die Wartezeit anhand der Uhr.

Wie wandle ich x-rate-limit-reset in eine Wartezeit um?

Ziehen Sie die aktuelle Unix-Zeit ab, denn der Wert ist ein absoluter Zeitstempel und keine Verzögerung. Der Beispielwert von X lautet 1705420800, und als Sekunden an einen Sleep-Aufruf übergeben, schläft der Worker rund 54 Jahre. Der Beispielcode von X wartet max(reset_time - time.time(), 60), also nie weniger als eine Minute.

Soll ich einen YouTube-Fehler quotaExceeded wiederholen?

Am selben Tag nicht. Ein quotaExceeded (403) bedeutet, dass das Tageskontingent aufgebraucht ist, und jede Anfrage, auch eine ungültige, kostet mindestens einen Punkt. Wiederholungen verbrauchen also nur mehr Kontingent. Die Obergrenze anzuheben ist ein Antragsverfahren.

Was liefert TikTok, wenn das tägliche Postinglimit erreicht ist?

Einen 403 mit dem Fehlercode spam_risk_too_many_posts, beschrieben als "Das tägliche Post-Limit der API ist für den aktuellen Nutzer erreicht." Es ist kein 429, deshalb sieht eine auf 429 ausgelegte Retry-Schleife ihn nie. Wer jeden 4xx wiederholt, hämmert umsonst auf den Endpunkt ein.

Soll ich weiter wiederholen, wenn Meta den Fehlercode 4 oder 17 liefert?

Die Aufrufe stoppen. Die Rate-Limiting-Referenz von Meta warnt, dass weitere Aufrufe den Aufrufzähler erhöhen und damit die Zeit verlängern, bis Aufrufe wieder gelingen. Der Error-Handling-Guide rät dagegen zu warten und zu wiederholen. Die beiden Seiten widersprechen sich, und die strengere Regel ist die sicherere.