Automatyzacja może działać poprawnie dla dziesięciu rekordów i zatrzymywać się przy tysiącu, choć token i adres API są prawidłowe. Przyczyną bywa rate limit API, czyli ograniczenie liczby lub kosztu żądań w określonym czasie. Dokładanie równoległych workerów zwykle wtedy pogarsza sytuację.
Pokażę, jak rozpoznać odpowiedź o przekroczeniu limitu, odczytać Retry-After i ustalić tempo pracy. Przykładowe liczby będą parametrami własnej polityki klienta, nie deklarowanymi limitami konkretnej usługi.
Rate limit API nie jest jednym licznikiem
Usługa może liczyć żądania na klucz API, użytkownika, organizację, adres IP albo konkretny endpoint. Niekiedy jedno kosztowne wywołanie zużywa więcej budżetu niż kilka prostych odczytów. Do tego dochodzą ograniczenia jednoczesnych operacji i limity dłuższego okresu rozliczeniowego.
Dlatego informacja „mam limit na minutę” nie wystarcza do napisania klienta. Sprawdź, czego dotyczy licznik, kiedy się odnawia i czy dostawca opisuje również limit krótkotrwałych skoków ruchu. Podstawy metod i odpowiedzi omawia wprowadzenie do REST API.
| Ograniczenie | Co kontroluje | Typowy błąd projektu |
|---|---|---|
| Tempo żądań | Liczbę operacji w przedziale czasu | Cała partia wysłana jednocześnie |
| Równoległość | Liczbę aktywnych wywołań | Zbyt wiele workerów na tym samym kluczu |
| Budżet kosztu | Punkty, tokeny lub koszt operacji | Liczenie wyłącznie liczby requestów |
| Limit dzienny lub planu | Dostępny przydział w dłuższym okresie | Ponawianie co sekundę mimo wyczerpanego przydziału |
Własna kolejka powinna więc kontrolować zarówno tempo, jak i liczbę żądań w locie. Sam limit wątków nie gwarantuje bezpiecznej liczby wywołań na sekundę.
Co oznacza HTTP 429 i kiedy pojawia się 403
Status 429 Too Many Requests informuje, że klient wykonał zbyt wiele żądań w danym czasie. Serwer może dołączyć nagłówek Retry-After, ale nie musi tego zrobić. Szczegóły przyczyny mogą być w treści odpowiedzi.
Nie każde API używa wyłącznie 429. Dokumentacja GitHuba opisuje również odpowiedzi 403 przy przekroczeniu określonych limitów. Nie oznacza to, że dowolne 403 wolno uznać za chwilowy problem i ponawiać. Ten sam status może informować o braku uprawnień.
Przy diagnozie zapisz status, identyfikator żądania i udokumentowane nagłówki limitu. Treść błędu obejrzyj po usunięciu danych wrażliwych. Do czytania zanonimizowanej odpowiedzi przydaje się formatter JSON. Nie zapisuj nagłówka Authorization, tokenów ani pełnych danych użytkowników w logach.
GitHub rozróżnia limity podstawowe i dodatkowe. Nagłówek x-ratelimit-reset ma tam konkretne znaczenie, ale nie wolno zakładać identycznej jednostki w każdym API. Pole zawierające liczbę może oznaczać czas Unix, liczbę sekund lub pozostały budżet.
Retry-After: sekundy albo data HTTP
Te dwie odpowiedzi wymagają odmiennego parsowania:
HTTP/1.1 429 Too Many Requests
Retry-After: 30
HTTP/1.1 429 Too Many Requests
Retry-After: Sun, 25 Oct 2026 14:00:30 GMT
Pierwsza prosi o odczekanie 30 sekund. Druga wskazuje moment w czasie. Użyj parsera dat HTTP i zegara ze strefą, zamiast usuwać litery z nagłówka i próbować interpretować resztę jako liczbę.
Jeśli serwer każe czekać godzinę, a zadanie ma budżet minuty, nie skracaj oczekiwania do minuty i nie wysyłaj kolejnego żądania. Zapisz termin ponownego wykonania w kolejce albo zakończ zadanie czytelnym błędem. Budżet klienta nie unieważnia ograniczenia dostawcy.
Dla daty w przeszłości można przyjąć zerowe dodatkowe oczekiwanie wynikające z samego nagłówka. Nadal obowiązuje lokalna kontrola tempa i limit prób. Powtarzające się stare daty są powodem do sprawdzenia zegara i zachowania serwera.
Przykład w Pythonie: wyznaczenie następnej próby
Poniższa funkcja oblicza czas oczekiwania. Nie wykonuje HTTP ani nie decyduje, czy konkretną operację wolno ponowić. Wywołuj ją dopiero po zaklasyfikowaniu odpowiedzi jako nadającej się do ponowienia zgodnie z dokumentacją API.
import random
from datetime import datetime, timezone
from email.utils import parsedate_to_datetime
def retry_delay(value, attempt, remaining, now=None):
"""Return delay or refuse a retry that exceeds the waiting budget."""
if attempt < 1 or remaining < 0:
raise ValueError('Invalid attempt or budget')
server_delay = None
if value is not None:
text = value.strip()
if text.isascii() and text.isdecimal():
server_delay = float(int(text))
else:
try:
date = parsedate_to_datetime(text)
if date.tzinfo is None:
raise ValueError('Missing timezone')
current = now or datetime.now(timezone.utc)
server_delay = max(0.0, (date - current).total_seconds())
except (ValueError, TypeError, OverflowError):
pass
if server_delay is None:
# Local policy, not a provider's published limit.
delay = random.uniform(1.0, min(30.0, 2.0 ** min(attempt, 5)))
else:
delay = server_delay + random.uniform(0.0, 0.5)
if delay > remaining:
raise TimeoutError('Defer the task: Retry-After exceeds the budget')
return delay
attempt zaczyna się od 1. remaining to pozostały budżet oczekiwania w sekundach. Gdy dostawca nie podał poprawnego Retry-After, przykład stosuje własne rosnące opóźnienie z losowaniem. Nie jest to uniwersalna polityka dla wszystkich API. Jeżeli dokumentacja wymaga dłuższej pauzy, zastąp nią tę gałąź.
Losowy dodatek do poprawnego nagłówka nie skraca wymaganej pauzy. Rozkłada natomiast kolejne próby klientów, które otrzymały tę samą informację. W kodzie produkcyjnym nie ma sensu utrzymywać uśpionego workera przez wiele godzin: lepiej zapisać zadanie z terminem next_attempt_at.
Przykład użycia bez wykonywania żądania:
delay = retry_delay("30", attempt=1, remaining=60)
print(f"Nastepna proba najwczesniej za {delay:.2f} s")
Funkcję sprawdzono lokalnie dla liczby sekund, daty HTTP, daty przeszłej, braku nagłówka, błędnej wartości i zbyt krótkiego budżetu. To test decyzji o oczekiwaniu, a nie test limitów zewnętrznej usługi.
Jak ograniczyć tempo jeszcze przed pierwszym 429
Załóżmy czysto demonstracyjny limit 60 żądań na minutę. Równomierny odstęp jednej sekundy daje średnio 60 wywołań na minutę, lecz nie stanowi gwarancji zgodności z oknami używanymi przez serwer. Dochodzą inne procesy, ponowienia i różnice w chwili rozpoczęcia okna.
Dla prostego pojedynczego skryptu zacznij od konserwatywnego odstępu i jednego aktywnego żądania. Wykorzystuj zegar monotoniczny do mierzenia lokalnych odstępów: zmiana czasu systemowego nie powinna skracać przerwy. Czas kalendarzowy jest potrzebny do interpretacji daty z nagłówka, ale nie do odmierzania upływu kilku sekund.
Jeśli pięć workerów korzysta z tego samego klucza, każdy nie może samodzielnie wykorzystać całego wspólnego budżetu. Potrzebny jest wspólny koordynator lub przydział części limitu. Centralna kolejka upraszcza też obsługę chwilowego zatrzymania wszystkich zadań dla konkretnego konta.
Nie próbuj omijać limitów przez rotację kont lub adresów. Najpierw zmniejsz liczbę zbędnych odczytów, połącz operacje tam, gdzie API to umożliwia, i sprawdź model rozliczenia dostawcy.
Mniej odpytywania, więcej pracy na zmianach
Pobieranie całej listy co minutę bywa głównym źródłem obciążenia. Jeśli API udostępnia filtr aktualizacji albo kursor, zapisuj punkt postępu. Gdy oferuje webhooki, można reagować na zdarzenia i okresowo uzgadniać stan zamiast ciągle pobierać wszystko.
Paginację traktuj jak część jednego zadania. Po błędzie zachowaj informację o ostatniej poprawnie obsłużonej stronie lub stabilnym kursorze. Nie zakładaj, że numery stron pozostają niezmienne przy równoczesnym dodawaniu rekordów.
Harmonogram z crona powinien uwzględniać czas wykonania. Nowe uruchomienie nie może co minutę dokładać kolejnej kopii wciąż pracującego importu. Przy pojedynczym serwerze pomocna jest blokada procesu; przy wielu hostach potrzebna jest koordynacja wspólna dla całego zadania.
Jak zastosować to w n8n i monitoringu
W węźle HTTP Request n8n dostępne są ustawienia wykonywania żądań partiami. To przydatne do prostego ograniczania tempa, ale osobne wykonania workflow mogą nadal korzystać ze wspólnego limitu. Samo opóźnienie między elementami jednego przebiegu tego nie rozwiązuje.
Oddziel trzy etapy: wykonanie żądania, rozpoznanie powodu błędu i decyzję o kolejnej próbie. Jeśli dopiero budujesz przepływ, zajrzyj do wprowadzenia do n8n. Nie włączaj ponawiania każdego błędu bez limitu i bez rozróżnienia operacji odczytu od zapisu.
Monitoruj liczbę 429, czas oczekiwania, długość kolejki i wiek najstarszego zadania. Wzrost liczby oczekujących rekordów pokazuje problem wcześniej niż pojedyncza awaria. Alarm można wysłać przez powiadomienie na Telegram, ale nie wysyłaj osobnej wiadomości dla każdej odrzuconej próby.
Najczęstsze pytania
Czy błąd 429 oznacza trwałą blokadę konta?
Nie musi. Zwykle informuje o ograniczeniu tempa lub przydziału, ale dokładną przyczynę trzeba sprawdzić w odpowiedzi i dokumentacji usługi. Dalsze agresywne odpytywanie może pogorszyć sytuację.
Co zrobić, gdy nie ma Retry-After?
Zastosuj udokumentowaną politykę dostawcy. Jeżeli jej nie ma, przyjmij ograniczoną liczbę prób, rosnące przerwy i losowanie opóźnienia. Po wyczerpaniu budżetu odłóż zadanie lub zgłoś błąd.
Czy limit równoległości zastępuje limit żądań na sekundę?
Nie. Jeden worker wykonujący bardzo szybkie odpowiedzi może wysłać wiele żądań w sekundę. Z kolei wolne wywołania mogą przekroczyć limit jednoczesnych operacji mimo niewielkiego tempa ich rozpoczynania.
Czy po 429 mogę ponowić POST?
Sprawdź kontrakt konkretnego endpointu i jego gwarancje dotyczące skutków operacji. Status błędu nie zastępuje obsługi idempotencji. Przy zapisie nie zakładaj, że każda nieudana odpowiedź oznacza brak zmiany po stronie serwera.
Jak testować obsługę limitu bez blokowania API?
Użyj lokalnego serwera testowego lub podstaw odpowiedzi z 429 i wybranym nagłówkiem. Sprawdź planowanie następnej próby, zakończenie po limicie oraz brak ponawiania trwałych błędów. Nie wywołuj celowo lawiny żądań do produkcyjnej usługi.
Źródła
- IETF: RFC 6585, status 429.
- IETF: RFC 9110, Retry-After i semantyka HTTP.
- GitHub Docs: limity REST API i odpowiedzi po ich przekroczeniu.
- Python: parsowanie dat nagłówków.
- Python: zegar monotoniczny.
- AWS: zasady retry, backoff i jitter w SDK.
- n8n: HTTP Request i przetwarzanie partiami.
Data publikacji: 25.10.2026.

Dyskusja