429 Too Many Requests: limity częstotliwości, Retry-After i fałszywe alarmy

Co oznacza 429 i co mu towarzyszy

429 jest zdefiniowane w RFC 6585 jako status ograniczania częstotliwości: klient wysłał zbyt wiele żądań w danym przedziale czasu. Specyfikacja celowo zostawia otwarte dwie rzeczy: jak serwer identyfikuje klienta i jak liczone są żądania. Dlatego limity częstotliwości tak bardzo różnią się między usługami.

W praktyce serwery liczą per adres IP, per klucz API, per sesję, per konto, albo per kombinację tych elementów, i używają stałych okien, przesuwających się okien albo koszyków tokenów. Dwie identyczne częstotliwości żądań mogą więc być w porządku na jednym endpoincie i zablokowane na innym w tej samej witrynie.

Odpowiedź niesie sygnały, których potrzebujesz:

• Retry-After to ten standardowy. RFC 9110 pozwala na liczbę sekund albo datę HTTP, a dobrze zachowujący się klient czeka tyle, zanim ponowi próbę.
• Nagłówki limitu częstotliwości, takie jak RateLimit-Limit, RateLimit-Remaining i RateLimit-Reset, albo starsze warianty X-RateLimit-, ujawniają budżet i moment jego zresetowania. To konwencje, a nie część RFC 9110, więc sprawdź dokładne nazwy w dokumentacji API.
• Treść powinna wyjaśniać limit w czytelnej dla człowieka formie. Wiele API nazywa, który limit został przekroczony, co oszczędza sporo zgadywania.

429 domyślnie nie podlega buforowaniu, więc pośrednicy nie powinni wciąż go serwować po zresetowaniu okna.

Limit częstotliwości czy prawdziwa awaria?

To się ciągle myli, bo oba objawiają się jako nieudane żądania. Rozróżniające testy są szybkie:

• Sam kod. Limit częstotliwości odpowiada 429. Przeciążony serwer albo serwer w trybie konserwacji odpowiada 503. Oba mogą nieść Retry-After, dlatego ludzie je mylą, ale oznaczają coś innego: 429 mówi "konkretnie Ty wysyłasz za dużo", 503 mówi "usługa jako całość nie może teraz przyjmować pracy". Zobacz poradnik o 503 po tę stronę.
• Czas odpowiedzi. Limity częstotliwości odrzucają szybko, zwykle w milisekundach, bo decyzja zapada, zanim wykona się jakakolwiek prawdziwa praca. Przeciążenie odpowiada wolno albo przekracza limit czasu.
• Kogo to dotyka. Limit częstotliwości trafia w jedną tożsamość klienta. Przetestuj z innego adresu IP albo z innym kluczem API: jeśli to się uda, podczas gdy ograniczony klient wciąż zawodzi, to limit, a nie awaria.
• Wzorzec w czasie. Ograniczanie częstotliwości jest okresowe i samo się kończy. Awarie skupiają się, potem ustają dokładnie w momencie zresetowania okna, a potem wracają. Awaria nie wznawia się grzecznie według harmonogramu.
• Korelacja z Twoim własnym wolumenem. Jeśli awarie zaczęły się, gdy podniosłeś częstotliwość sprawdzeń, dodałeś równoległych pracowników albo uruchomiłeś zadanie wsadowe, przyczyna leży po Twojej stronie połączenia.

Dlaczego monitoring może sam wyzwolić 429

Monitoring to powtarzające się żądanie z małego zestawu adresów do tego samego URL, co jest bliskie kształtowi, który limitery częstotliwości są zbudowane, żeby wyłapywać. Bardzo krótki interwał sprawdzenia pogarsza sytuację, bo sprawdzenia co minutę pomnożone przez wiele monitorowanych adresów URL szybko sumują się do limitu per IP. Tak samo działa uruchomienie sprawdzenia z wielu lokalizacji naraz: serwer źródłowy widzi wybuch, a nie stały strumień, a limity wybuchowe uruchamiają się pierwsze.

Wybór URL też ma znaczenie. Strony wyszukiwania, endpointy API i wszystko, co zapisuje, są zwykle ograniczane mocniej niż statyczna strona główna. A jeśli monitoring i aplikacja dzielą jeden klucz API, oba rywalizują o pojedynczy budżet. Wynikiem jest monitor zgłaszający, że witryna zawodzi, podczas gdy witryna jest całkowicie zdrowa, a limiter częstotliwości poprawnie wykonuje swoją pracę.

Jak naprawić 429

1. Przeczytaj nagłówki odpowiedzi, zanim cokolwiek zmienisz:

   curl -sS -o /dev/null -D - https://example.com/api/items

   Retry-After i wszelkie nagłówki limitu częstotliwości mówią Ci prawdziwy budżet, co bije zgadywanie interwałów.
2. Respektuj Retry-After. Natychmiastowe ponowienie próby w wielu implementacjach przedłuża blokadę. Czekaj podany czas.
3. Wycofuj się wykładniczo z losowym rozrzutem (jitter) w kodzie klienta, żeby równoległe klienty się nie zsynchronizowały i nie ponawiały prób jak stado.
4. Obniż częstotliwość żądań. Dla monitoringu przenieś sprawdzany endpoint na dłuższy interwał, albo rozłóż sprawdzenia w czasie, żeby wiele lokalizacji nie uruchamiało się w tej samej sekundzie.
5. Monitoruj tani, reprezentatywny URL. Lekki endpoint zdrowia albo strona główna mówią Ci, że witryna działa, nie wydając budżetu potrzebnego dla prawdziwego ruchu.
6. Zwolnij klienta monitorującego z limitu. Umieść adresy punktów kontrolnych na białej liście albo daj monitoringowi własny klucz API z własnym budżetem, żeby nigdy nie rywalizował z ruchem produkcyjnym.
7. Jeśli to Ty jesteś właścicielem limitera, sprawdź, czy limit jest odpowiedni. Zapytaj, czy budżet odpowiada rzeczywistemu użyciu, czy jest per IP, podczas gdy powinien być per konto, i czy współdzielone proxy albo firmowy NAT nie stawiają wielu użytkowników za jednym adresem.

Obserwowanie 429 bez ich wywoływania

Limity częstotliwości zwykle pojawiają się najpierw dla najbardziej aktywnych klientów, co oznacza, że płacący klienci i integracje trafiają na nie, zanim zrobi to ktokolwiek z Twojego zespołu. Zaplanowane sprawdzenie HTTP, które potwierdza oczekiwany kod statusu, pokazuje 429 jako odrębne zdarzenie z sygnaturą czasową, a nie jako rozproszone zgłoszenia "API jest niestabilne", a moment jego wystąpienia mówi, czy limit jest okresowy, czy stały. Ustaw interwał świadomie: na tyle często, żeby szybko zauważyć problemy, na tyle łagodnie, żeby sprawdzenie nigdy samo nie było tym, co wyzwala limit. Szerszą rodzinę odmów, w tym 401 i 403, opisuje przegląd 4xx.