Jak stosować limity zapytań w API katalogu branżowego

Limit zapytań w API katalogu branżowego nie jest drobnym parametrem technicznym. To mechanizm, który decyduje, czy integracja będzie działała stabilnie, czy zatrzyma się w połowie importu firm, wyszukiwania wykonawców albo aktualizacji danych kontaktowych.

Najczęstszy błąd polega na wysyłaniu zapytań tak szybko, jak pozwala serwer aplikacji. Na środowisku testowym wszystko działa, bo przetwarzanych jest kilkadziesiąt rekordów. Problem zaczyna się przy pobieraniu 20–100 tys. wpisów albo równoczesnej obsłudze kilku klientów. API zwraca wtedy kod 429 Too Many Requests, część danych nie zostaje zapisana, a źle zaprojektowany mechanizm ponawiania jeszcze bardziej zwiększa ruch.

Limitu nie należy traktować jako przeszkody do obejścia. Trzeba włączyć go do architektury integracji: kontrolować tempo, ograniczać liczbę równoległych połączeń, zapisywać postęp i ponawiać wyłącznie te operacje, które rzeczywiście się nie udały.

Jak odczytać limit i przeliczyć go na rzeczywiste tempo pracy

Dostawcy API opisują limity na kilka sposobów. Najczęściej spotykane warianty to:

• określona liczba zapytań na sekundę, na przykład 5 req/s;
• liczba zapytań na minutę, na przykład 300 req/min;
• dzienny limit operacji, na przykład 10 000 zapytań na dobę;
• osobny limit dla jednego klucza API, konta, adresu IP albo konkretnego endpointu;
• limit współbieżności, na przykład maksymalnie 3 aktywne żądania jednocześnie.

Te parametry nie są równoważne. Limit 300 zapytań na minutę nie musi oznaczać, że można wysłać 300 żądań w pierwszych pięciu sekundach i później czekać. Serwer może stosować ruchome okno czasowe albo algorytm token bucket, który dopuszcza krótki skok ruchu, lecz później ogranicza kolejne wywołania.

Najpierw trzeba sprawdzić dokumentację endpointu oraz nagłówki odpowiedzi. W praktyce przydatne są między innymi:

• RateLimit-Limit albo X-RateLimit-Limit – maksymalna liczba operacji w oknie;
• RateLimit-Remaining albo X-RateLimit-Remaining – liczba dostępnych operacji;
• RateLimit-Reset – moment odnowienia puli;
• Retry-After – czas oczekiwania przed kolejną próbą, zwykle podany w sekundach albo jako data HTTP.

Nazwy nagłówków nie są jednak jednolite. Część dostawców zwraca je tylko po przekroczeniu limitu, inni nie pokazują ich wcale. Dlatego integracja nie może zakładać, że każdy serwer udostępni komplet informacji.

Przed uruchomieniem importu należy wykonać test na małej próbce, na przykład 500 rekordach, i zapisać:

• średni czas odpowiedzi;
• liczbę odpowiedzi 429;
• liczbę błędów 500–504;
• maksymalną liczbę stabilnych połączeń równoległych;
• rzeczywistą liczbę rekordów przetwarzanych w ciągu minuty.

Jeżeli API pozwala na 300 zapytań na minutę, bezpieczne tempo produkcyjne warto początkowo ustawić na około 240–270 zapytań na minutę, czyli 80–90% deklarowanego limitu. Zapas jest potrzebny dla operacji ręcznych, zapytań wykonywanych przez panel administracyjny oraz krótkich różnic w sposobie liczenia okna czasowego.

Przykład: przy limicie 5 zapytań na sekundę i jednym rekordzie zwracanym w odpowiedzi pobranie 50 tys. firm zajmie teoretycznie około 2 godz. 47 min. W praktyce trzeba doliczyć opóźnienia sieciowe, ponowienia i okresowe błędy. Realny czas będzie bliższy 3–3,5 godziny. Jeżeli endpoint zwraca po 100 rekordów na stronę, ten sam zbiór wymaga już tylko 500 zapytań i może zostać pobrany w mniej niż dwie minuty.

Dlatego przed zwiększaniem limitu trzeba sprawdzić paginację i wielkość strony. Zmiana parametru limit=20 na limit=100 często daje większy efekt niż uruchamianie kolejnych procesów równoległych.

Kolejka, ponawianie i ochrona przed lawiną błędów

Stabilna integracja nie powinna wysyłać zapytań bezpośrednio z pętli wykonującej kolejne rekordy. Lepszym rozwiązaniem jest kolejka z kontrolą przepustowości.

Podstawowy mechanizm powinien obejmować:

1. kolejkę zadań do wykonania;
2. ograniczenie liczby żądań w jednostce czasu;
3. limit równoległych połączeń;
4. zapis statusu każdego zadania;
5. obsługę kodów odpowiedzi;
6. kontrolowane ponawianie nieudanych operacji.

Dla API o limicie 10 zapytań na sekundę rozsądną konfiguracją początkową będzie 8 zapytań na sekundę i maksymalnie 2–4 równoległe połączenia. Większa liczba workerów nie zawsze przyspiesza pracę. Jeżeli dostawca liczy wszystkie żądania wspólnie dla jednego klucza, dziesięć procesów tylko szybciej wyczerpie pulę.

Po otrzymaniu kodu 429 klient powinien w pierwszej kolejności respektować nagłówek Retry-After. Gdy serwer go nie zwraca, należy zastosować wykładnicze zwiększanie przerw, najlepiej z losowym przesunięciem:

• pierwsza próba po około 1 sekundzie;
• druga po 2 sekundach;
• trzecia po 4 sekundach;
• czwarta po 8 sekundach;
• piąta po 16 sekundach.

Do każdej wartości dobrze dodać losowe odchylenie rzędu 10–30%. Bez tego kilka workerów może wznowić pracę w tej samej milisekundzie i ponownie przeciążyć endpoint. Zjawisko to nazywa się efektem stada.

Nie należy ponawiać wszystkich błędów w identyczny sposób:

• 400 Bad Request zwykle oznacza błędne dane lub parametry; ponowienie bez zmiany zapytania niczego nie naprawi;
• 401 Unauthorized wymaga sprawdzenia klucza, tokenu lub podpisu;
• 403 Forbidden może oznaczać brak uprawnień albo wyczerpanie planu;
• 404 Not Found najczęściej powinien zakończyć przetwarzanie danego rekordu;
• 429 Too Many Requests wymaga przerwy;
• 500, 502, 503 i 504 można ponowić po kontrolowanym opóźnieniu.

Praktycznym limitem jest zwykle 3–5 prób. Po piątym niepowodzeniu zadanie powinno trafić do kolejki błędów, a nie wracać bez końca do głównego obiegu. Nieskończone ponawianie jest jednym z najbardziej irytujących błędów w integracjach katalogowych: zużywa limit, zaciemnia logi i może przez wiele godzin blokować poprawne rekordy.

Trzeba też zapisywać punkt kontrolny, na przykład numer strony, identyfikator ostatniej firmy albo znacznik czasu ostatniej synchronizacji. Bez checkpointu awaria przy 80% importu oznacza ponowne pobranie całości. To nie tylko strata czasu. W API rozliczanym pakietowo może również oznaczać niepotrzebny koszt.

Jak ograniczyć liczbę zapytań bez utraty aktualności danych

Najtańsze zapytanie to takie, którego nie trzeba wysyłać. W katalogach branżowych duża część danych zmienia się rzadko: nazwa firmy, miejscowość, branża czy numer KRS zwykle nie wymagają odświeżania co kilka minut.

Częstotliwość synchronizacji powinna zależeć od rodzaju danych:

• dostępność usługi, status ogłoszenia lub stan rezerwacji: co 5–30 minut;
• ceny, godziny otwarcia i bieżące dane ofertowe: co 1–6 godzin;
• telefon, adres strony i opis firmy: co 24–72 godziny;
• dane rejestrowe i klasyfikacja branżowa: co 7–30 dni.

Nie jest to uniwersalny harmonogram narzucony przez dostawcę API, lecz praktyczny punkt startowy. Częstsze odświeżanie ma sens tylko wtedy, gdy użytkownik rzeczywiście korzysta z informacji, które tak szybko się zmieniają.

Największą oszczędność daje synchronizacja przyrostowa. Zamiast codziennie pobierać cały katalog, aplikacja powinna pytać o rekordy zmienione od ostatniego udanego uruchomienia, na przykład przez parametry:

• updated_since;
• modified_after;
• changed_from;
• zakres dat from i to;
• kursor zwrócony przez poprzednią odpowiedź.

Jeżeli API nie oferuje filtrowania po dacie modyfikacji, można rozdzielić proces na dwa poziomy. Dane aktywnie używanych firm odświeżać codziennie, a pozostałe partiami, na przykład po 5% bazy dziennie. W ten sposób pełny cykl aktualizacji obejmie 20 dni, ale obciążenie będzie równomierne.

Drugim narzędziem jest pamięć podręczna. Odpowiedź wyszukiwania dla tej samej branży i lokalizacji można zachować na 15–60 minut, zamiast ponownie pytać API przy każdym wejściu użytkownika. Profile firm można przechowywać dłużej, na przykład 24 godziny, o ile regulamin dostawcy pozwala na lokalne magazynowanie danych.

Cache nie może jednak ukrywać zmian bez końca. Każdy zapis powinien mieć:

• czas utworzenia;
• termin ważności;
• wersję danych lub ETag, jeżeli API ją udostępnia;
• procedurę wymuszonego odświeżenia;
• zasadę usuwania wpisów wycofanych z katalogu.

W praktyce dobrze działa model stale-while-revalidate: użytkownik od razu otrzymuje ostatnią poprawną wersję danych, a aplikacja aktualizuje ją w tle podczas obsługi bieżącego procesu. Nie należy jednak stosować tego mechanizmu dla informacji krytycznych, takich jak potwierdzenie dostępności, cena transakcyjna czy status płatności. Tam odpowiedź musi pochodzić z aktualnego źródła.

Trzeba też sprawdzić, czy API obsługuje zapytania zbiorcze. Endpoint przyjmujący 50 identyfikatorów w jednym wywołaniu zmniejsza ruch wielokrotnie. Nie zawsze jest jednak szybszy. Duże paczki dłużej się przetwarzają, częściej kończą się timeoutem, a jeden błędny rekord może odrzucić całą operację. Bezpieczny rozmiar partii to zwykle 20–100 rekordów, ale właściwą wartość należy ustalić na podstawie testów konkretnego endpointu.

Przy planowaniu własnego katalogu, integracji danych firmowych albo mechanizmu wyszukiwania dostawców dodatkowe informacje można znaleźć na stronie aiqo.pl.

Najpierw należy usunąć najdroższy błąd: ponawianie zapytań bez ograniczenia i bez sprawdzania kodu odpowiedzi. Dopiero później warto zwiększać równoległość. Kolejność działań powinna być konkretna: odczytać rzeczywisty limit, ustawić tempo na 80–90% tej wartości, wdrożyć obsługę 429 z Retry-After, zapisać checkpoint i dopiero na końcu testować większe paczki oraz dodatkowe workery.

FAQ

Czy każde przekroczenie limitu kończy się kodem 429?
Nie. Część API zwraca 403, komunikat o wyczerpaniu planu albo własny kod błędu w treści odpowiedzi. Integracja powinna sprawdzać zarówno status HTTP, jak i strukturę komunikatu błędu.

Ile zapytań równoległych warto uruchomić?
Na początek 2–4. Liczbę należy zwiększać dopiero wtedy, gdy monitoring pokazuje brak odpowiedzi 429, stabilne czasy odpowiedzi i niewykorzystany limit. Dziesięć workerów nie daje przewagi, gdy wspólna pula wynosi pięć zapytań na sekundę.

Czy po błędzie 429 można od razu ponowić zapytanie?
Nie. Najpierw trzeba odczytać Retry-After. Jeżeli nagłówka nie ma, pierwszą próbę należy wykonać po około sekundzie, a kolejne opóźniać wykładniczo.

Jak długo przechowywać odpowiedzi w pamięci podręcznej?
Dla wyników wyszukiwania zazwyczaj 15–60 minut, dla profili firm 12–24 godziny, a dla danych rejestrowych nawet kilka dni. Okres musi odpowiadać rzeczywistemu tempu zmian i warunkom licencyjnym API.

Czy wyższy abonament zawsze rozwiązuje problem limitów?
Nie. Wyższy pakiet zwiększa pulę, ale nie naprawia braku paginacji, nieskończonych ponowień, podwójnych importów ani zapytań wykonywanych przy każdym odsłonięciu strony. Najpierw trzeba ograniczyć zbędny ruch.

Co monitorować po uruchomieniu integracji?
Co najmniej liczbę zapytań na minutę, odsetek kodów 429, liczbę ponowień, czas odpowiedzi, wielkość kolejki, liczbę trwale odrzuconych zadań oraz czas pełnej synchronizacji.

Czy można automatycznie wykorzystywać 100% dostępnego limitu?
Technicznie tak, ale jest to ryzykowne. Krótkie skoki ruchu, ręczne operacje administracyjne i różnice w sposobie liczenia okna mogą powodować błędy. Stabilniejszym celem jest 80–90% limitu.

Od czego zacząć przy istniejącej, niestabilnej integracji?
Od logów odpowiedzi HTTP. Najpierw policz kody 429 i sprawdź, czy aplikacja respektuje Retry-After. Jeżeli nie, napraw mechanizm ponawiania przed zmianą abonamentu, zwiększaniem liczby workerów lub przebudową całego importu.