Jak długo czekać po osiągnięciu limitu zapytań w KSeF?

Zazwyczaj wystarczy kilkadziesiąt sekund do kilku minut. W API czas do resetu limitu może być podany w nagłówku X-RateLimit-Reset lub Retry-After. W razie wątpliwości zaleca się odczekanie 1–2 minut przed ponowną próbą.

Osiągnąłeś limit zapytań w KSeF – co to znaczy i co zrobić

Q: Osiągnąłeś limit zapytań w KSeF – co to znaczy?

Komunikat "Osiągnąłeś limit zapytań" oznacza, że w danym przedziale czasowym wykonano już maksymalną dozwoloną liczbę żądań do KSeF. System stosuje rate limiting i tymczasowo blokuje kolejne zapytania. Po odczekaniu (zwykle kilkadziesiąt sekund do kilku minut) limit się odświeża i można kontynuować pracę. W API to samo zjawisko objawia się kodem HTTP 429.

Q: Co zrobić, gdy w KSeF wyświetli się limit zapytań?

Należy odczekać chwilę przed kolejną operacją. W portalu nie należy wielokrotnie odświeżać strony ani masowo powtarzać zapytań. W API przy błędzie 429 należy zastosować retry z opóźnieniem (np. wykładniczy backoff) i ewentualnie sprawdzić nagłówek Retry-After. Długoterminowo warto rozkładać operacje w czasie i monitorować nagłówki limitów.

Komunikat "Osiągnąłeś limit zapytań" w KSeF pojawia się, gdy w krótkim czasie wykonasz zbyt wiele operacji. Wyjaśniamy, co to oznacza i jak postępować w portalu oraz przy integracji API.

Co musisz wiedzieć

Komunikat "Osiągnąłeś limit zapytań" (lub "Osiągnąłeś limit zapytania") w Krajowym Systemie e-Faktur oznacza, że w danym przedziale czasowym wykonano zbyt wiele żądań. System ogranicza liczbę zapytań, aby zapewnić stabilność usługi i sprawiedliwy dostęp dla wszystkich użytkowników.

Limit może dotyczyć zarówno Aplikacji Podatnika KSeF (portal w przeglądarce), jak i wywołań API. W API przekroczenie limitu skutkuje odpowiedzią HTTP 429 (Too Many Requests). W portalu użytkownik widzi komunikat o osiągnięciu limitu zapytań.

To zabezpieczenie techniczne, a nie błąd konfiguracji. Po odczekaniu krótkiego czasu lub po resecie okna limitowego możesz kontynuować pracę. Poniżej znajdziesz konkretne kroki i odpowiedzi na częste pytania.

Najczęstsze problemy i rozwiązania

Komunikat "Osiągnąłeś limit zapytań" w portalu po wielu operacjach

Odczekaj kilkadziesiąt sekund lub 1–2 minuty. Ogranicz wielokrotne odświeżanie i masowe powtarzanie wyszukiwań lub eksportów. W kolejnych sesjach rozłóż operacje w czasie.

Błąd 429 (Too Many Requests) przy wywołaniach API

Zaimplementuj retry z wykładniczym backoffem: po otrzymaniu 429 poczekaj (np. 5–30 s), potem ponów żądanie; przy kolejnych 429 zwiększ czas oczekiwania. Sprawdź nagłówek Retry-After. Monitoruj X-RateLimit-Remaining i zmniejsz częstotliwość żądań, gdy limit jest bliski wyczerpania.

Limit zapytań przy masowej wysyłce faktur

Używaj sesji wsadowej (batch) do wysyłki wielu faktur – to ogranicza liczbę wywołań. Rozłóż uruchomienia w czasie. Sprawdź dokumentację limitów dla operacji wsadowych i dostosuj tempo wysyłki.

Co oznacza komunikat "Osiągnąłeś limit zapytań"

Komunikat informuje, że w danym przedziale czasowym (np. na sekundę, minutę lub godzinę) wykonano już maksymalną dozwoloną liczbę operacji. KSeF stosuje mechanizm rate limiting: po przekroczeniu limitu kolejne żądania są blokowane do momentu "odświeżenia" okna. W API odpowiedzią jest wtedy błąd HTTP 429 (Too Many Requests). W portalu użytkownik widzi komunikat tekstowy o osiągnięciu limitu. Limity są różne dla różnych operacji (np. wyszukiwanie metadanych, eksport paczek) oraz dla środowisk testowych i produkcyjnych.

Limit w portalu KSeF a limit w API

W Aplikacji Podatnika KSeF (portal na stronie podatki.gov.pl) każda czynność użytkownika generuje żądania do systemu. Szybkie wykonywanie wielu operacji (np. wielokrotne wyszukiwanie, eksport) może spowodować wyświetlenie komunikatu "Osiągnąłeś limit zapytań". W integracji przez API to samo zjawisko objawia się kodem 429. W obu przypadkach chodzi o ten sam mechanizm ograniczania liczby żądań w czasie. Dokumentacja API (np. nagłówki X-RateLimit-Limit, X-RateLimit-Remaining) opisuje limity dla wywołań programowych.

Co zrobić, gdy zobaczysz ten komunikat

W portalu: odczekaj kilkadziesiąt sekund lub kilka minut, zanim wykonasz kolejną operację. Unikaj wielokrotnego odświeżania strony lub masowego powtarzania tych samych zapytań. W API: przy błędzie 429 poczekaj przed ponownym żądaniem; sprawdź nagłówek Retry-After (jeśli jest zwracany). Zaimplementuj retry z wykładniczym backoffem: po 429 zwiększ czas oczekiwania przed kolejną próbą. Odczytywanie nagłówków X-RateLimit-Remaining pozwala dostosować częstotliwość żądań i uniknąć przekraczania limitu.

Jak uniknąć przekroczenia limitu

Rozłóż operacje w czasie – unikaj wysyłania dużej liczby żądań w krótkim przedziale. W API korzystaj z sesji wsadowych do masowej wysyłki faktur zamiast wielu pojedynczych wywołań. Monitoruj nagłówki limitów w odpowiedziach (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) i zmniejsz tempo żądań, gdy zbliżasz się do limitu. W środowisku produkcyjnym podmioty z wyższym zapotrzebowaniem mogą wnioskować o podwyższenie limitów przez oficjalny kanał kontaktowy Ministerstwa Finansów.

FAQ

Osiągnąłeś limit zapytań – co to znaczy?

Oznacza to, że w danym przedziale czasowym wykonano już maksymalną dozwoloną liczbę żądań do KSeF. System tymczasowo blokuje kolejne zapytania. Po odczekaniu (zwykle kilkadziesiąt sekund do kilku minut) limit się odświeża i możesz kontynuować.

Co zrobić, gdy w KSeF wyświetli się limit zapytań?

Poczekaj chwilę przed kolejną operacją. W portalu nie odświeżaj strony wielokrotnie i nie powtarzaj masowo tych samych zapytań. W API przy błędzie 429 zastosuj retry z opóźnieniem (np. wykładniczy backoff) i ewentualnie sprawdź nagłówek Retry-After.

Jak długo czekać po osiągnięciu limitu zapytań?

Zazwyczaj wystarczy kilkadziesiąt sekund do kilku minut. W API czas do resetu limitu bywa podawany w nagłówku X-RateLimit-Reset lub Retry-After. W razie wątpliwości odczekaj 1–2 minuty przed ponowną próbą.

Czy "Osiągnąłeś limit zapytań" i błąd 429 to to samo?

Tak. W API przekroczenie limitu skutkuje kodem HTTP 429 (Too Many Requests). W portalu użytkownik zamiast tego widzi komunikat o osiągnięciu limitu zapytań. Oba przypadki oznaczają to samo zjawisko – rate limiting.

Czy mogę zwiększyć limit zapytań w KSeF?

Dla środowiska produkcyjnego podmioty z uzasadnioną potrzebą wyższej intensywności mogą składać wniosek o podwyższenie limitów przez oficjalny formularz kontaktowy Ministerstwa Finansów. Wniosek powinien zawierać opis zastosowania i uzasadnienie.

Powiązane tematy

Przydatne serwisy

Status KSeF

Pierwszy serwis prezentuje informacje o statusie samego KSeF, drugi – komunikaty techniczne Ministerstwa Finansów.