Słownik

Dlaczego w większości API mediów społecznościowych brakuje 429 Retry-After

Taras Shynkarenko
Taras Shynkarenko
•Zaktualizowano: •9 min czytania
Odpowiedź HTTP 429 z nagłówkiem Retry-After obok sygnałów limitów pięciu platform społecznościowychOdpowiedź HTTP 429 z nagłówkiem Retry-After obok sygnałów limitów pięciu platform społecznościowych

TL;DR, szybka odpowiedź

9 min czytania

RFC 6585 definiuje kod 429 Too Many Requests i mówi, że odpowiedź MOŻE zawierać nagłówek Retry-After, który RFC 9110 określa jako liczbę sekund albo datę HTTP. Żadne z pięciu dużych API społecznościowych nie dokumentuje jego wysyłania. X odsyła do x-rate-limit-reset, czyli uniksowego znacznika czasu. Meta sygnalizuje limity kodami błędów 4, 17, 32, 613 i 80001 i nigdy nie podaje statusu HTTP. LinkedIn zwraca 429 bez udokumentowanych nagłówków, a limity odnawia o północy UTC. TikTok zwraca 429 z rate_limit_exceeded. YouTube zgłasza wyczerpany limit jako 403, a nie 429.

Co oznacza 429 Retry-After?

Odpowiedź 429 z Retry-After to informacja serwera, że klient wysłał zbyt wiele żądań, i opcjonalnie wskazówka, ile poczekać przed następnym. Obie części pochodzą z dwóch różnych specyfikacji.

RFC 6585 definiuje kod statusu: "The 429 status code indicates that the user has sent too many requests in a given amount of time ("rate limiting")." Następnie czyni nagłówek opcjonalnym: "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."

Sam nagłówek definiuje RFC 9110 w sekcji 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." Dalej sekcja opisuje znaczenie nagłówka przy kodzie 503 i przekierowaniach 3xx. Kodu 429 w ogóle nie wymienia. Powiązanie kodu statusu z nagłówkiem istnieje wyłącznie w RFC 6585 i ma tam postać MAY.

RFC 6585 pozostawia też liczenie serwerowi: "Note that this specification does not define how the origin server identifies the user, nor how it counts requests." To jedno zdanie tłumaczy, dlaczego każda z poniższych platform zachowuje się inaczej. Standard daje im kod statusu i opcjonalny nagłówek, i nic więcej.

Jeśli przed klientem API stoi pamięć podręczna, RFC 6585 ma dla niej jeszcze jedną regułę: "Responses with the 429 status code MUST NOT be stored by a cache."

Jak parsować wartość Retry-After?

RFC 9110 dopuszcza dwie postacie: "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

Postać z sekundami to "a non-negative decimal integer, representing time in seconds", a RFC wprost wyjaśnia, że drugi przykład oznacza opóźnienie o 2 minuty. Parser musi obsłużyć obie. Najpierw spróbuj liczby całkowitej, a potem daty:

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

Rzędy samochodów stojących w korku na autostradzie, obraz serwera odrzucającego żądania, gdy naraz przychodzi ich zbyt wiele.

Które API mediów społecznościowych wysyłają nagłówek Retry-After?

Żadne z pięciu, jeśli wierzyć ich własnej dokumentacji. Każde sygnalizuje limit po swojemu, a dwa z nich nie zawsze używają kodu 429.

PlatformaStatus przy limicieSygnał w treści odpowiedziSygnał czasu w dokumentacjiUdokumentowane Retry-After
X429code: 88, "Rate limit exceeded"x-rate-limit-reset, uniksowy znacznik czasuNie
Meta Graph APINiepodanyerror.code równy 4, 17, 32, 613 lub 80001estimated_time_to_regain_access w minutach, tylko dla business use caseNie
LinkedIn429"Resource level throttle limit for calls to this resource is reached."Brak, limity dzienne odnawiają się o północy UTCNie
TikTok429rate_limit_exceededBrak, minutowe okno przesuwneNie
YouTube403 dla limitu, 429 tylko dla miniaturquotaExceeded, uploadRateLimitExceededBrakNie

Bluesky i Pinterest mają własne schematy nagłówków, które opisujemy w omówieniu limitów API Bluesky i zestawieniu limitów API Pinterest.

Jak API X sygnalizuje limit?

Kodem 429 i trzema nagłówkami w każdej odpowiedzi. Strona o limitach X: "Exceeding limits results in a 429 error until the window resets." Dokumentuje ona x-rate-limit-limit jako "Maximum requests allowed", x-rate-limit-remaining jako "Requests remaining in window" i x-rate-limit-reset jako "Unix timestamp when window resets."

Właśnie z pola x-rate-limit-reset należy korzystać, a jest to czas bezwzględny, nie opóźnienie. Przykładowa wartość X to 1705420800. Przekaż ją do funkcji sleep jako sekundy, a proces zaśnie na około 54 lata, więc najpierw odejmij bieżący czas uniksowy. Własna strategia X ma trzy kroki: "Check x-rate-limit-reset for when the window resets", "Wait until that time before retrying", "Use exponential backoff if needed." Przykładowy kod X czeka max(reset_time - time.time(), 60), czyli nigdy krócej niż minutę.

X dokumentuje dwie różne treści odpowiedzi dla tej samej sytuacji. Strona o limitach pokazuje kod 429 zwracający {"errors": [{"code": 88, "message": "Rate limit exceeded"}]}. Strona o kodach odpowiedzi opisuje błędy jako obiekty z polami type, title i detail oraz wymienia typ .../rate-limit-exceeded. Dopasowuj po statusie HTTP, a obie postacie traktuj jako limit.

Ta sama strona dodaje haczyk. X definiuje 429 jako "Rate limit or usage cap exceeded" i wymienia osobny typ błędu .../usage-capped. Kod 429 spowodowany limitem użycia nie znika po upływie x-rate-limit-reset. Sprawdź typ błędu, zanim zaplanujesz ponowienie na czas odnowienia.

Jak Meta sygnalizuje limit?

Kodami błędów w treści JSON. Wymieniają je dokumentacja limitów Meta i przewodnik po obsłudze błędów, ale żadna z tych stron nie podaje, jaki status HTTP im towarzyszy.

AdaptlyPost
AdaptlyPost

Rozpocznij 7-dniowy bezpłatny okres próbny

Analityka wszystkich platform

Skrzynka społecznościowa

Asystent oparty na AI

KodCo mówi Meta
4"Indicates that the app whose token is being used in the request has reached its rate limit."
17"Indicates that the User whose token is being used in the request has reached their rate limit."
32"Indicates that the User or app whose token is being used in the Pages API request has reached its rate limit."
613"Indicates that a custom rate limit has been reached."
80001"There have been too many calls to this Page account. Wait a bit and try again."

Meta przeczy sama sobie w kwestii tego, co robić dalej. Przewodnik po obsłudze błędów mówi o kodach 4 i 17: "Temporary issue due to throttling. Wait and retry the operation, or examine your API request volume." Dokumentacja limitów mówi natomiast: "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." Trzymaj się surowszej wersji, bo ponawianie według zasad Meta wydłuża blokadę.

Sygnał czasu zależy od tego, który z dwóch systemów limitów Meta cię zatrzymał. Nagłówek business use case zawiera estimated_time_to_regain_access, zdefiniowane jako "Time, in minutes, until calls will not longer be throttled." Zwróć uwagę na jednostkę: Retry-After liczy w sekundach, a to pole w minutach. Nagłówek na poziomie aplikacji w ogóle nie ma pola czasu, co szczegółowo opisuje omówienie nagłówka x-app-usage.

Zbliżenie na analogowy zegar ścienny, symbol limitów odnawianych o stałej porze, na przykład o północy UTC.

Jak LinkedIn i TikTok sygnalizują limit?

Oba zwracają zwykły kod 429 i nie dokumentują nagłówków z czasem.

Strona LinkedIna o limitach: "Rate limited requests will receive a 429 response." Strona o obsłudze błędów podaje komunikat: "Resource level throttle limit for calls to this resource is reached." LinkedIn nie publikuje też samych limitów: "Standard rate limits are not published in documentation." Znajdziesz je na karcie Analytics w Developer Portal, i to tylko dla endpointów wywołanych co najmniej raz danego dnia według UTC.

Czas wynika tu z kalendarza, a nie z nagłówka. LinkedIn podaje, że limity obejmują "a 24 hour period" i "reset at midnight UTC every day." Po kodzie 429 wywołanym twoją własną liczbą żądań najwcześniejsze sensowne ponowienie przypada na najbliższą godzinę 00:00 UTC. LinkedIn wysyła 429 także z przyczyn niezależnych od ciebie: "In rare cases, LinkedIn may also return a 429 response as part of infrastructure protection. API service will return to normal automatically." Nic w odpowiedzi nie pozwala odróżnić tych dwóch przypadków.

Strona TikToka o limitach: "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." Podaje ona 600 żądań dla każdego z endpointów /v2/user/info/, /v2/video/query/ i /v2/video/list/. Endpoint publikacji jest znacznie ciaśniejszy. Dokumentacja Content Posting API mówi o /v2/post/publish/video/init/: "Each user access_token is limited to 6 requests per minute."

Dzienny limit publikacji na TikToku nie jest kodem 429. To 403 z spam_risk_too_many_posts, opisane jako "The daily post cap from the API is reached for the current user." Pętla ponowień oparta na 429 nigdy go nie zobaczy, a pętla ponawiająca każdy błąd 4xx będzie uderzać w niego na próżno.

Jak YouTube sygnalizuje błąd limitu?

Najczęściej kodem 403. Lista błędów YouTube wymienia quotaExceeded (403): "The request cannot be completed because you have exceeded your quota." Ten błąd oznacza wyczerpany limit dzienny i nie jest kodem 429.

Przegląd YouTube podaje domyślny budżet: "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." Zaznacza też, że "All API requests, including invalid requests, incur at least a one-point quota cost", więc nieudane ponowienia również zużywają limit.

Jedyny kod 429 na liście błędów YouTube dotyczy miniatur: tooManyRequests (429) uploadRateLimitExceeded, "The channel has uploaded too many thumbnails recently. Please try the request again later." Dzienny limit przesyłania to jeszcze inny status, badRequest (400) uploadLimitExceeded, z wymownym opisem: "This is a YouTube platform restriction and is entirely separate from your Google Cloud project's API quota." Błędu quotaExceeded nie da się ponowić tego samego dnia. Podniesienie pułapu wymaga formalności, które opisujemy w tekście o rozszerzeniu limitu API YouTube.

Co powinna robić polityka ponowień, gdy brakuje Retry-After?

Odczytaj własny sygnał platformy i zanim cokolwiek ponowisz, oddziel limity dzienne od limitów częstotliwości.

Jeśli odpowiedź zawiera Retry-After, zastosuj się do niego. W przeciwnym razie weź czas oczekiwania od platformy: x-rate-limit-reset minus bieżący czas dla X, estimated_time_to_regain_access w minutach dla limitów business use case w Meta, najbliższa północ UTC dla LinkedIna i co najmniej minuta dla okna przesuwnego TikToka. Przy błędach Meta na poziomie aplikacji zatrzymaj kolejkę i sprawdź X-App-Usage, zanim wznowisz pracę.

Następnie osobno obsłuż błędy, które wyglądają na limity częstotliwości, ale nimi nie są: spam_risk_too_many_posts z TikToka, quotaExceeded i uploadLimitExceeded z YouTube oraz limit użycia X. To pułapy dzienne i żadnego z nich nie usunie backoff liczony w sekundach.

Kolejność decyzji o ponowieniu
1
Sklasyfikuj błąd. Pułapy dzienne, takie jak spam_risk_too_many_posts z TikToka, quotaExceeded i uploadLimitExceeded z YouTube oraz limit użycia X, nie znikają dzięki backoffowi. Przestań je ponawiać.
2
Poszukaj Retry-After. Jeśli odpowiedź go zawiera, zastosuj się do niego.
3
Odczytaj sygnał platformy. x-rate-limit-reset minus bieżący czas dla X, estimated_time_to_regain_access w minutach dla Meta, najbliższa północ UTC dla LinkedIna, co najmniej minuta dla TikToka.
4
Sprawdź błędy Meta na poziomie aplikacji. Zatrzymaj kolejkę i sprawdź X-App-Usage, zanim wznowisz pracę.
Najpierw oddziel pułapy od limitów częstotliwości, bo backoff liczony w sekundach usuwa tylko te drugie.

Najczęściej zadawane pytania

Czy nagłówek Retry-After jest wymagany w odpowiedzi 429?

Nie. RFC 6585 mówi, że odpowiedź 429 "MAY include a Retry-After header indicating how long to wait before making a new request." Poziom SHOULD dotyczy tylko wyjaśnienia sytuacji.

AdaptlyPost
AdaptlyPost

Rozpocznij 7-dniowy bezpłatny okres próbny

Analityka wszystkich platform

Skrzynka społecznościowa

Asystent oparty na AI

Jakie formaty może mieć nagłówek Retry-After?

RFC 9110 dopuszcza datę HTTP, np. Fri, 31 Dec 1999 23:59:59 GMT, albo nieujemną liczbę całkowitą sekund, np. 120. Parsery muszą obsługiwać obie postacie.

Czy API X wysyła Retry-After przy kodzie 429?

Strony X o limitach i błędach tego nie dokumentują. Odsyłają do x-rate-limit-reset, uniksowego znacznika czasu odnowienia okna, a przykładowy kod X czeka co najmniej 60 sekund.

Jaki status HTTP zwraca Facebook Graph API przy limicie?

Meta nie podaje tego ani w dokumentacji limitów, ani w przewodniku po obsłudze błędów. Obie strony rozpoznają limity po polu code w treści błędu JSON: 4, 17, 32, 613 lub 80001 dla limitów business use case na stronach.

Czy YouTube Data API zwraca 429 po wyczerpaniu limitu?

Nie. Wyczerpany limit zwraca 403 z przyczyną quotaExceeded. Jedyny kod 429 na liście błędów YouTube to uploadRateLimitExceeded przy przesyłaniu miniatur.

Kiedy odnawia się limit API LinkedIna?

O północy UTC. Strona LinkedIna o limitach mówi, że obejmują one okres 24 godzin i "reset at midnight UTC every day." LinkedIn nie dokumentuje nagłówka odnowienia, więc czas oczekiwania oblicz z zegara.

Jak zamienić x-rate-limit-reset na czas oczekiwania?

Odejmij od niego bieżący czas uniksowy, bo to bezwzględny znacznik czasu, a nie opóźnienie. Przykładowa wartość X to 1705420800, a przekazanie jej do funkcji sleep jako sekund usypia proces na około 54 lata. Przykładowy kod X czeka max(reset_time - time.time(), 60), czyli nigdy krócej niż minutę.

Czy ponawiać błąd quotaExceeded z YouTube?

Nie tego samego dnia. quotaExceeded (403) oznacza, że limit dzienny jest wyczerpany, a każde żądanie, także nieprawidłowe, kosztuje co najmniej jeden punkt, więc ponowienia tylko zużywają więcej limitu. Podniesienie pułapu wymaga formalności.

Co zwraca TikTok po osiągnięciu dziennego limitu publikacji?

Kod 403 z błędem spam_risk_too_many_posts, opisanym jako "The daily post cap from the API is reached for the current user." To nie jest 429, więc pętla ponowień oparta na 429 go nie zobaczy. Pętla ponawiająca każdy błąd 4xx będzie uderzać w niego na próżno.

Czy ponawiać żądania, gdy Meta zwraca kod błędu 4 lub 17?

Przestań wysyłać żądania. Dokumentacja limitów Meta ostrzega, że dalsze wywołania zwiększają ich licznik, a przez to wydłużają czas do ponownego powodzenia. Przewodnik po obsłudze błędów zaleca odczekanie i ponowienie, więc te strony są ze sobą sprzeczne, a surowsza zasada jest bezpieczniejsza.

Czy ten artykuł był pomocny?

Chętnie poznamy opinię!

Więcej naszych treści w Google

Jedno kliknięcie oznacza AdaptlyPost jako preferowane źródło, dzięki czemu nasze artykuły pojawiają się wyżej w Najważniejszych wiadomościach, trybie AI i Podsumowaniach AI.

Jeszcze chwila...

AdaptlyPost

AdaptlyPost

Planowanie treści na wszystkich platformach

Wszystkie konta społecznościowe w jednym miejscu dzięki AdaptlyPost.

Analityka wszystkich platform

Skrzynka społecznościowa

Asystent oparty na AI

Powiązane hasła ze słownika

Powiązane artykuły