Limit zapytań KSeF: komunikat w portalu i kod 429 w API

Jedno zjawisko, dwa interfejsy

Limit zapytań KSeF objawia się różnie w zależności od tego, przez co korzystasz z systemu. W Aplikacji Podatnika zobaczysz komunikat tekstowy o limicie zapytań. W API ten sam mechanizm zwykle objawia się kodem HTTP 429 (Too Many Requests). W obu przypadkach oznacza to, że w krótkim czasie wykonano więcej operacji, niż dopuszcza mechanizm ochrony systemu przed przeciążeniem.

Warto od razu odnotować rzecz, która bywa zaskoczeniem: limit nie jest przypisany do osoby ani do przeglądarki, tylko do kontekstu, w którym pracujesz — w połączeniu z adresem IP, z którego wychodzą żądania. Twoje kliknięcia w portalu, praca współpracownika w tej samej sieci firmowej i program księgowy działający na tym samym łączu zużywają więc wspólny budżet. Integracja wychodząca z innego adresu — na przykład usługa księgowa w chmurze — ma budżet osobny, mimo że pracuje na tym samym podmiocie. Komunikat potrafi się przez to pojawić w sytuacji, w której subiektywnie nic intensywnego nie robiłeś.

Dlaczego system w ogóle ogranicza liczbę zapytań

Limit bywa odbierany jako utrudnienie, ale pełni konkretną funkcję. KSeF obsługuje wszystkich podatników w kraju, a pojedyncza integracja odpytująca system w pętli potrafi obciążyć go nieproporcjonalnie do swoich rzeczywistych potrzeb. Mechanizm ograniczania żądań chroni stabilność systemu i zapewnia, że budżet wydajności rozkłada się równo między użytkowników.

Ma to praktyczną konsekwencję dla sposobu, w jaki warto myśleć o tym komunikacie: to nie jest usterka do naprawienia, tylko granica do uwzględnienia w planowaniu pracy. Ta różnica przekłada się wprost na reakcję — przy usterce szuka się przyczyny i zgłasza problem, przy granicy dostosowuje się tempo.

Co robić w portalu

• Nie odświeżaj strony wielokrotnie – każde odświeżenie to kolejne żądanie.
• Odczekaj od kilkudziesięciu sekund do kilku minut i spróbuj ponownie.
• Rozłóż w czasie wyszukiwania i eksporty danych, zwłaszcza w godzinach większego obciążenia.
• Jeśli to możliwe, spróbuj innej metody logowania (np. Profil Zaufany, podpis kwalifikowany) – czasem problem dotyczy konkretnej ścieżki logowania.

Jeżeli komunikat pojawia się już przy pierwszej próbie, warto sprawdzić komunikaty Ministerstwa Finansów o utrudnieniach – może to oznaczać ogólne przeciążenie systemu.

Ile trwa limit zapytań KSeF

Najczęstsze pytanie przy tym komunikacie brzmi "ile to potrwa" — i odpowiedź jest mniej precyzyjna, niż większość osób oczekuje, ale za to praktyczna.

Nie ma jednej liczby, którą dałoby się podać — i to jest istotne, bo oszczędza wpatrywania się w zegar. Czas blokady jest dynamiczny: zależy od tego, jak bardzo limit został przekroczony i jak często zdarzało się to wcześniej.

W praktyce oznacza to dwie rzeczy:

• Krótkie przekroczenie mija szybko — zwykle w kilkadziesiąt sekund do kilku minut.
• Uporczywe ponawianie wydłuża blokadę. Każde odświeżenie liczy się jako kolejne żądanie, więc próba "przeczekania przez klikanie" działa dokładnie odwrotnie do zamierzenia.

Najprostsza reguła praktyczna: po zobaczeniu komunikatu zostaw kartę w spokoju na minutę lub dwie i zajmij się czymś innym. Powrót po tym czasie kończy się powodzeniem znacznie częściej niż seria natychmiastowych prób, a przy okazji nie pogłębia problemu.

Jeśli po kilku minutach komunikat nadal się pojawia, nie znaczy to jeszcze, że problem leży po stronie systemu. KSeF liczy limity równolegle w kilku przesuwnych oknach — sekundowym, minutowym i godzinowym — więc po wyczerpaniu budżetu godzinowego blokada utrzymuje się, dopóki starsze żądania nie wyjdą poza ostatnie 60 minut. Najpierw sprawdź więc własny ruch z ostatniej godziny (integracja w tle, duży eksport, seria odświeżeń) i czas podany w Retry-After, jeśli korzystasz z API. Dopiero gdy nic tego nie tłumaczy, warto sprawdzić komunikaty Ministerstwa Finansów o utrudnieniach.

Skąd limit przy "normalnej" pracy

Komunikat potrafi pojawić się bez intensywnego klikania. Najczęstsze przyczyny:

Integracja działa w tle. Limity dotyczą kontekstu i adresu IP, nie pojedynczego narzędzia. Jeśli firma ma program księgowy synchronizujący faktury z KSeF z tej samej sieci, jego żądania zużywają ten sam budżet co Twoja praca w przeglądarce. Komunikat w portalu bywa skutkiem tego, że właśnie ruszyła synchronizacja.

Kilka osób pracuje na tym samym podmiocie. Ten sam mechanizm — wspólny kontekst i wspólne łącze firmowe oznaczają wspólny limit.

Duży eksport lub szerokie wyszukiwanie. Operacje obejmujące wiele dokumentów zużywają nieproporcjonalnie dużo budżetu. Pobranie listy faktur za cały rok to nie jedno żądanie.

Odświeżanie po wcześniejszym błędzie. Jeśli coś nie działało i strona była odświeżana wielokrotnie, limit mógł zostać wyczerpany właśnie wtedy.

Co robić w API

Jeśli komunikat dotyczy integracji, a nie przeglądarki, obowiązuje inny zestaw działań:

1. Obsłuż kod HTTP 429 w swoim kliencie – odczytaj nagłówek Retry-After, odczekaj wskazany czas i ponów żądanie.
2. Zastosuj rosnące odstępy między próbami (tzw. backoff wykładniczy) – przy kolejnych błędach wydłużaj czas oczekiwania.
3. Ogranicz częstotliwość wywołań (np. synchronizacji danych czy pobierania faktur) – patrz Limity zapytań do API KSeF, gdzie znajdziesz konkretne wartości limitów dla poszczególnych operacji.
4. Tam, gdzie to możliwe, korzystaj z operacji zbiorczych (np. eksport paczek danych) zamiast wielu pojedynczych zapytań.

Warto też wiedzieć, że domyślne limity środowiska testowego są od wersji API 2.5.0 zrównane z produkcyjnymi (wcześniej były wyższe), a środowisko Demo ma je identyczne z produkcją. Jeśli integracja przechodziła testy bez 429, a po wdrożeniu zaczyna je zwracać, sprawdź, czy na środowisku testowym nie działał nadpisany profil limitów.

Jak ograniczyć ryzyko, że limit zablokuje pracę

Limit najbardziej boli wtedy, gdy trafia w momencie, w którym faktury muszą wyjść. Kilka nawyków wyraźnie zmniejsza szansę na taki scenariusz.

Rozłóż pracę masową w czasie. Eksport faktur za cały rok albo szerokie wyszukiwanie zużywają nieproporcjonalnie duży budżet żądań. Jeśli wiesz, że czeka Cię taka operacja, lepiej wykonać ją poza szczytem — nie tuż przed terminem, gdy każda minuta blokady jest kosztowna.

Ustal z księgowością, kto i kiedy synchronizuje. Gdy kilka osób pracuje na tym samym podmiocie, a w tle działa jeszcze program księgowy, budżet żądań dzieli się między nich wszystkich. Uzgodnienie, że masowe pobrania nie odbywają się równolegle, kosztuje jedno zdanie ustaleń.

Sprawdź, czy integracja nie odpytuje za często. Program księgowy synchronizujący faktury co kilka minut potrafi samodzielnie wyczerpać limit godzinowy, zostawiając Cię z komunikatem w przeglądarce, choć sam nic nie kliknąłeś. Częstotliwość synchronizacji to zwykle ustawienie, nie stała.

Nie traktuj limitu jako awarii. To mechanizm ochronny działający zgodnie z projektem. Zgłoszenie do infolinii ma sens dopiero wtedy, gdy komunikat pojawia się przy pierwszej próbie po dłuższej przerwie w pracy — czyli gdy w ostatniej godzinie nie było ani Twoich żądań, ani synchronizacji w tle, które mogłyby wyczerpać budżet.

Kiedy limit nie jest przyczyną

Trzy sytuacje bywają brane za limit zapytań, choć nim nie są — a każda prowadzi do innego rozwiązania:

Portal ładuje się długo, ale bez komunikatu. To zwykle obciążenie systemu albo problem po stronie przeglądarki. Odczekanie pomoże, ale z innego powodu niż przy limicie.

Logowanie kończy się błędem uprawnień, zanim wejdziesz do portalu. Komunikat o braku dostępu, nieważnym certyfikacie albo nierozpoznanym podmiocie to nie limit — przyczyny szukaj w metodzie uwierzytelnienia, uprawnieniach albo dostępności usługi, która potwierdza tożsamość. Uwaga: samo logowanie nie jest wolne od limitów — publiczne operacje uwierzytelniania (jak pobranie wyzwania) mają własny budżet liczony per adres IP, więc 429 albo komunikat o limicie na tym etapie nadal oznacza ograniczenie liczby żądań, a nie problem z uprawnieniami.

Faktura została odrzucona przy wysyłce. To wynik walidacji dokumentu — komunikat o limicie ani go nie spowodował, ani nie zniknie po odczekaniu.

W dwóch ostatnich przypadkach — błędzie uprawnień i odrzuceniu faktury — odczekanie i ponowna próba nie zmieniają wyniku, bo przyczyna jest gdzie indziej. Wolne ładowanie portalu jest tu wyjątkiem: tam odczekanie pomaga, tyle że z powodu obciążenia systemu, a nie limitu Twoich żądań.

Jak tego nie mylić z błędem uprawnień

Kody 401 i 403 dotyczą zwykle uwierzytelnienia lub uprawnień, a nie liczby zapytań. Po ustąpieniu limitu warto wrócić do sprawdzenia uprawnień i kontekstu: Błąd 401 – uprawnienia, token, kontekst.

Biura rachunkowe — limit przy wielu podmiotach

Przy obsłudze kilku firm mechanizm działa inaczej, niż podpowiada intuicja, i warto to wiedzieć zanim komunikat pojawi się w środku pracy.

Limit liczy się per kontekst, czyli per podmiot, w którym akurat działasz. Przełączenie się na innego klienta oznacza inny budżet żądań — komunikat dotyczący jednej firmy nie blokuje pracy nad kolejną. To dobra wiadomość: praca nie zatrzymuje się w całości.

Gorsza strona tej samej zasady: budżet podmiotu dzielisz z jego innymi integracjami pracującymi z tego samego adresu IP. Jeśli klient ma własny program księgowy synchronizujący faktury z Twojej sieci albo przez to samo łącze, jego żądania zużywają ten sam limit co Twoja praca w portalu. Przy kilkunastu klientach obsługiwanych równolegle to zmienia sposób planowania — masowe operacje warto rozłożyć na podmioty i na godziny, zamiast uruchamiać wszystko w jednym oknie czasowym.

Praktyczny wniosek: gdy komunikat pojawia się regularnie u tego samego klienta, a u pozostałych nie, sprawdź w pierwszej kolejności integracje wychodzące z tego samego adresu co Twoja praca w portalu — to one dzielą budżet. Program księgowy pracujący u klienta, z jego własnego łącza, ma inny adres wyjściowy i osobny budżet, więc nie wyczerpie limitu widocznego w biurze. Jeśli żadna integracja nie korzysta ze wspólnego adresu, przyczyny szukaj w intensywności własnej pracy na tym kontekście, nie po stronie klienta.

Co zanotować, jeśli zgłaszasz problem

Komunikat o limicie rzadko wymaga zgłoszenia, ale gdy pojawia się uporczywie i przy pierwszej próbie, warto mieć przygotowane cztery informacje:

1. Godzinę wystąpienia — pozwala odróżnić szczyt obciążenia od problemu indywidualnego.
2. Co robiłeś bezpośrednio wcześniej — szczególnie czy był to eksport, szerokie wyszukiwanie albo seria odświeżeń.
3. Czy w tle działa integracja i z jaką częstotliwością synchronizuje.
4. Czy problem dotyczy jednego podmiotu, czy wszystkich — to rozróżnia limit kontekstu od ogólnej niedostępności systemu.

Ostatni punkt rozstrzyga najczęściej i zajmuje kilkanaście sekund: wystarczy przełączyć kontekst na inny podmiot i sprawdzić, czy tam praca idzie normalnie.

Czego KSeF nie sprawdza

Komunikat o limicie zapytań dotyczy częstotliwości operacji w portalu lub API, a nie poprawności faktur ani uprawnień do ich treści. Po odczekaniu problem z limitem ustępuje — to nie naprawia błędów merytorycznych w dokumentach.

Jak można to zweryfikować automatycznie

W integracjach stosuj obsługę HTTP 429 z Retry-After i backoffem. Rozłóż synchronizację w czasie i korzystaj z operacji zbiorczych zamiast wielu pojedynczych zapytań — szczegóły w Limity zapytań do API KSeF.

FAQ

Powiązane artykuły

• Limity zapytań do API KSeF – rate limiting – techniczne limity i kod 429
• KSeF: pobieranie faktur krok po kroku – jak bezpiecznie pobierać faktury
• Problemy z logowaniem do KSeF – kategorie – kiedy limit zapytań to nie jedyny problem

Treść ma charakter informacyjny i edukacyjny. Nie stanowi porady prawnej ani podatkowej.