Komunikat „osiągnąłeś limit zapytań” w KSeF – portal i API
Jedno zjawisko, dwa interfejsy
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.
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.
Co robić w API
- Obsłuż kod HTTP 429 w swoim kliencie – odczytaj nagłówek
Retry-After, odczekaj wskazany czas i ponów żądanie. - Zastosuj rosnące odstępy między próbami (tzw. backoff wykładniczy) – przy kolejnych błędach wydłużaj czas oczekiwania.
- Ogranicz częstotliwość wywołań (np. synchronizacji danych czy pobierania faktur) – patrz Limity zapytań do API KSeF.
- Tam, gdzie to możliwe, korzystaj z operacji zbiorczych (np. eksport paczek danych) zamiast wielu pojedynczych zapytań.
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.
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
Czy wielokrotne odświeżanie strony pomoże przy limicie zapytań?
Nie — każde odświeżenie to kolejne żądanie i może pogorszyć sytuację. Lepiej odczekać kilkadziesiąt sekund do kilku minut.
Czy limit zapytań to to samo co błąd 401?
Nie. 429 oznacza zbyt wiele żądań w krótkim czasie; 401/403 dotyczą uwierzytelnienia lub uprawnień.
Czy limit w portalu i w API to ten sam mechanizm?
Tak — w praktyce to ten sam rodzaj ochrony systemu, tylko widoczny jako komunikat tekstowy w przeglądarce albo kod HTTP 429 w API.
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.
Przydatne serwisy
Pierwszy serwis prezentuje informacje o statusie samego KSeF, drugi – komunikaty techniczne Ministerstwa Finansów.