Jak projektować integracje odporne na limity API
Najczęstszy błąd to traktowanie limitu jako problemu, który rozwiąże się obsługą błędu. Integracja, która wysyła zapytania bez kontroli i dopiero po 429 zwalnia, przez większość czasu działa na granicy blokady, a w szczycie sprzedaży traci minuty na odczekiwanie. Lepiej przyjąć kilka zasad projektowych już na etapie budowy:
Jeden ogranicznik na API i konto - wszystkie procesy integracji (zamówienia, stany, ceny, oferty) korzystają ze wspólnego licznika zapytań, zamiast liczyć każdy osobno.
Czytanie sygnałów z odpowiedzi - integracja odczytuje nagłówki i pola o zużyciu limitu i zwalnia, zanim dostanie 429.
Kolejka z priorytetami - pobranie zamówień i zmiana stanu przy sprzedaży idą przed aktualizacją opisów i zdjęć.
Operacje zbiorcze - jeśli API pozwala zaktualizować wiele produktów w jednym wywołaniu, integracja z tego korzysta.
Zdarzenia zamiast odpytywania - webhooki i dzienniki zdarzeń zastępują cykliczne pobieranie list, w których nic się nie zmieniło.
Pamięć podręczna danych słownikowych - kategorie, parametry czy metody dostawy pobiera się raz i odświeża rzadko.
Webhooki to jedna z najskuteczniejszych metod oszczędzania limitu, bo integracja dostaje informację o zmianie, zamiast co minutę sprawdzać, czy coś się wydarzyło. Wymagają jednak weryfikacji nadawcy, idempotencji i okresowego uzgadniania danych, o czym piszemy we wpisie webhooki w e-commerce - do czego służą i jak je bezpiecznie wdrożyć.
Ponawianie po błędzie 429 - odstęp wykładniczy i losowy rozrzut
Nawet dobrze zaprojektowana integracja czasem dostanie 429, np. gdy z tego samego konta korzysta inna aplikacja. Wtedy liczy się sposób ponawiania. Amazon w artykule z serii Builders' Library o limitach czasu, ponowieniach i odstępach zaleca wydłużanie odstępu po każdej nieudanej próbie z górnym ograniczeniem, dodanie losowego rozrzutu (jitter), żeby wiele procesów nie ponawiało zapytań w tej samej chwili, ograniczenie liczby prób i ponawianie tylko w jednym miejscu stosu, bo ponowienia na kilku warstwach mnożą obciążenie. Shopify w dokumentacji limitów rekomenduje odczekanie co najmniej sekundy przed kolejnym zapytaniem po przekroczeniu limitu (stan na lipiec 2026 - sprawdź aktualną dokumentację Shopify).
Przełożone na integrację sklepu, ponawianie po 429 wygląda tak:
[#chart:wpr84b]
Ważne jest rozróżnienie błędów. 429 i błędy serwera z grupy 5xx zwykle mają sens ponawiać. Błędy 400, 401 czy 403 oznaczają problem z samym zapytaniem, tokenem lub uprawnieniami i ponawianie ich bez zmian tylko zużywa limit. Jak czytać poszczególne kody w integracji sklepu, opisujemy we wpisie integracja przestała działać - lista kontrolna diagnozy.
Idempotencja - ponowienie bez duplikatów
Ponowienie jest bezpieczne tylko wtedy, gdy dwukrotne wykonanie tej samej operacji daje ten sam wynik. Odczyt danych i ustawienie stanu na konkretną wartość są z natury bezpieczne. Utworzenie zamówienia w ERP, wystawienie faktury czy zamówienie kuriera - już nie. Jeśli odpowiedź na takie zapytanie nie dotarła, integracja nie wie, czy operacja się wykonała. Dlatego przy operacjach tworzących dane zapisuje się identyfikator źródłowy, np. numer zamówienia z marketplace'u, i przed ponowieniem sprawdza, czy rekord już istnieje. Wiele API pozwala też przekazać własny identyfikator operacji, po którym serwer rozpozna powtórzenie.
Budżet limitu - jak podzielić zapytania między zadania
Limit to wspólny zasób wszystkich procesów integracji. Jeśli nocna aktualizacja opisów zużyje całą pulę, pobieranie zamówień zacznie dostawać 429. Dlatego warto zaplanować budżet: jaka część limitu jest zarezerwowana dla zadań krytycznych, jaka dla zadań cyklicznych, a jaka zostaje jako zapas na ponowienia i nagłe skoki ruchu. Przykładowy podział dla integracji z jednym marketplace'em może wyglądać tak:
[#chart:wpr84c]
Liczby w takim budżecie wynikają z pomiaru, a nie z założeń. Integracja powinna zapisywać, ile zapytań wykonuje każdy proces, żeby po tygodniu było widać, co naprawdę zużywa limit. Często okazuje się, że największym konsumentem jest zadanie, które co minutę pobiera pełną listę ofert, choć zmienia się w niej kilka pozycji dziennie. Zmiana takiego zadania na pobieranie tylko rekordów zmienionych od ostatniej synchronizacji potrafi zwolnić większą część limitu bez żadnych kosztów po stronie platformy. Budżet warto przeglądać po każdym dodaniu nowego procesu do integracji, bo każdy kolejny proces korzysta z tej samej puli.
Operacje zbiorcze i masowe aktualizacje
Największą oszczędność limitu daje zwykle zmiana sposobu wysyłania danych, a nie droższy plan. Base pozwala zaktualizować stany do 1000 produktów w jednym wywołaniu metody updateInventoryProductsStock, więc aktualizacja całego katalogu może zająć kilka zapytań zamiast kilku tysięcy. Shopify do dużych odczytów udostępnia operacje masowe (bulk operations), które według dokumentacji nie mają limitów kosztu i liczby zapytań obowiązujących pojedyncze zapytania GraphQL (stan na lipiec 2026 - sprawdź aktualną dokumentację Base i Shopify).
Przy masowych zmianach, np. przecenie całej kategorii, warto też rozłożyć pracę w czasie: zacząć od produktów z największą sprzedażą, wysyłać paczki danych w stałym tempie i mierzyć, kiedy zmiany są widoczne we wszystkich kanałach. Integracja, która próbuje wypchnąć wszystko naraz, kończy zwykle w pętli błędów 429 i wydłuża całą operację. Przy przecenach o ustalonej godzinie lepiej przygotować dane wcześniej i zacząć wysyłkę z wyprzedzeniem, jeśli platforma pozwala zaplanować zmianę.
[#tip] Przy integracjach z Allegro dodatkowym ograniczeniem jest kubełek liczony na użytkownika dla wybranych zasobów. Zbyt wiele równoległych zapytań w imieniu tego samego konta kończy się 429, nawet gdy limit Client ID jest daleko. Dlatego liczba równoległych wątków na jedno konto sprzedawcy powinna być ustawiana świadomie, a nie maksymalnie.
Kilka kont i kilka sklepów w jednej integracji
Limity rzadko są liczone globalnie. Shopify liczy je dla pary aplikacja-sklep, Allegro dla Client ID, a dla wybranych zasobów także dla konkretnego użytkownika. Ma to znaczenie, gdy jedna integracja obsługuje kilka kont sprzedawcy albo kilka sklepów. Ogranicznik zapytań musi wtedy prowadzić osobne liczniki dla każdego konta i wspólny dla aplikacji, a kolejka powinna rozdzielać pracę tak, żeby jedno duże konto nie zablokowało pozostałych. Przy integracjach budowanych dla wielu klientów dochodzi jeszcze jedna zasada: plan sklepu wpływa na limit, więc ta sama integracja może potrzebować innych ustawień tempa na różnych sklepach.
Jak testować obsługę limitów przed wdrożeniem
Obsługę 429 trudno sprawdzić na produkcji, bo nikt nie chce celowo blokować konta. Lepiej przetestować ją w sandboxie lub na atrapie API, która zwraca 429 z nagłówkiem Retry-After co kilka zapytań. Według dokumentacji Allegro główny limit obowiązuje także w środowisku testowym, więc sandbox pozwala sprawdzić zachowanie integracji przy dużej liczbie zapytań. Test powinien potwierdzić, że integracja zwalnia, nie gubi danych, nie tworzy duplikatów i po ustąpieniu blokady nadrabia zaległości w rozsądnym czasie.
Monitoring zużycia limitów API
O problemie z limitami lepiej dowiedzieć się z wykresu niż od klienta, któremu nie dotarło potwierdzenie zamówienia. Minimalny monitoring obejmuje liczbę odpowiedzi 429 na godzinę z podziałem na API i proces, zużycie limitu odczytane z nagłówków lub pól odpowiedzi, długość kolejki zadań i czas oczekiwania najstarszego zadania. Alert powinien przyjść, gdy błędy 429 pojawiają się stale, a nie pojedynczo, albo gdy kolejka zamówień rośnie dłużej niż kilka minut. Jak ustawić takie powiadomienia bez fałszywych alarmów, opisujemy we wpisie monitoring integracji i alerty o błędach.
Najczęstsze błędy w obsłudze limitów API
Każdy proces liczy limit osobno, więc razem przekraczają pulę, choć każdy z osobna mieści się w normie.
Ponawianie natychmiast i bez końca, które po 429 wydłuża blokadę i zużywa limit innych zadań.
Ponawianie na kilku warstwach naraz: w bibliotece HTTP, w kodzie integracji i w kolejce.
Brak idempotencji, przez który ponowione utworzenie zamówienia lub faktury daje duplikat.
Odpytywanie pełnych list co minutę zamiast zdarzeń lub filtrowania po dacie zmiany.
Ignorowanie nagłówka Retry-After i informacji o zużyciu zwracanych przez API.
Jak Vinson pomaga z limitami API w integracjach
Zapewniamy wsparcie programistyczne dla sklepów i sprzedawców: integracje, automatyzacje, poprawki i rozwój sklepów oraz narzędzi. Mierzymy, które procesy zużywają limity API, wprowadzamy wspólny ogranicznik zapytań, kolejki z priorytetami, operacje zbiorcze i ponawianie z odstępem, zabezpieczamy integracje przed duplikatami i dodajemy monitoring zużycia limitów. Szczegóły znajdziesz na stronie Wsparcie programistyczne dla e-commerce.
Najczęściej zadawane pytania
Co oznacza błąd 429 w integracji sklepu?
Błąd 429 Too Many Requests oznacza, że integracja wysłała zbyt wiele zapytań do API w danym czasie i przekroczyła limit platformy. Integracja powinna odczekać, najlepiej tyle, ile wskazuje nagłówek Retry-After, i ponowić zapytanie. Częste błędy 429 to sygnał, że trzeba zmniejszyć liczbę zapytań.
Jaki jest limit zapytań API Allegro?
Według dokumentacji Allegro główny limit to 9000 zapytań na minutę na Client ID, a po jego przekroczeniu Client ID jest blokowany na minutę. Wybrane zasoby mają niższe limity, a dla części działa dodatkowe ograniczenie na użytkownika (stan na lipiec 2026 - sprawdź aktualną dokumentację Allegro).
Jak działa limit w Shopify GraphQL Admin API?
Shopify liczy koszt zapytań w punktach, które odnawiają się co sekundę: 100 na planie podstawowym, 200 na Advanced i 1000 na Plus. Pojedyncze zapytanie nie może kosztować więcej niż 1000 punktów, a stan limitu jest zwracany w polu extensions.cost odpowiedzi (stan na lipiec 2026 - sprawdź aktualną dokumentację Shopify).
Czy warto ponawiać zapytania po błędzie 429?
Tak, ale z rosnącym odstępem, losowym rozrzutem i ograniczoną liczbą prób, w jednym miejscu integracji. Ponawiać można bez obaw odczyty i operacje idempotentne. Przy tworzeniu zamówień, faktur czy przesyłek trzeba najpierw sprawdzić, czy poprzednia próba się nie wykonała.
Jak zmniejszyć liczbę zapytań do API w integracji?
Używaj operacji zbiorczych, webhooków i dzienników zdarzeń zamiast cyklicznego odpytywania, przechowuj w pamięci podręcznej dane, które rzadko się zmieniają, i pobieraj tylko rekordy zmienione od ostatniej synchronizacji. Najpierw zmierz, który proces zużywa najwięcej zapytań.
Limity API nie znikną, ale integracja może z nimi współpracować zamiast z nimi walczyć. Jeśli Twoje integracje regularnie dostają błędy 429 albo nie nadążają w szczycie sprzedaży, sprawdź wsparcie programistyczne Vinson.
