Co oznacza błąd 429 / limit zapytań w KSeF?
HTTP 429 to sygnał z API Krajowego Systemu e-Faktur, że w krótkim czasie wysłano zbyt wiele zapytań dla danej pary NIP + adres IP – oficjalny limit Ministerstwa Finansów to 20 zapytań na godzinę dla metadanych i eksportów paczek oraz 64 na godzinę dla pojedynczej faktury. To nie awaria: KSeF Import sam pilnuje tych progów i automatycznie ponawia zapytanie po czasie z nagłówka Retry-After, więc w praktyce zwykle nic nie zauważysz.
- Limit zapytań API KSeF to oficjalny mechanizm Ministerstwa Finansów: ok. 20 zapytań/godz. dla metadanych i eksportów paczek, 64/godz. dla pojedynczej faktury – licznik działa w przesuwającym się oknie czasowym (sliding window), nie od pełnej godziny zegarowej.
- KSeF Import trzyma własny bufor poniżej tych progów (np. 60 zamiast 64, 18 zamiast 20) i pilnuje go osobno dla każdego NIP-u oraz łącznie dla całej infrastruktury.
- Gdy limit mimo to zostanie osiągnięty, system czeka dokładnie tyle, ile wskazuje nagłówek Retry-After, i ponawia próbę – bez Twojego udziału.
- W biurach z wieloma NIP-ami ryzyko rośnie, bo limity liczą się per para kontekst+adres IP – dlatego osobny dystrybuowany zamek synchronizacji chroni każdy NIP przed kolizją ręcznego i zaplanowanego pobrania.
- Jeśli pobieranie utknie na dłużej niż kilkanaście minut, częstszą przyczyną niż sam limit zapytań są cofnięte uprawnienia certyfikatu.
W tym artykule
Od problemu do efektu
PWENowe faktury pojawiają się z opóźnieniem albo w logach widać „przekroczono limit zapytań” lub kod 429 – bez wyjaśnienia, czy to problem po Twojej stronie, czy normalne zachowanie systemu.
To udokumentowany mechanizm ochronny KSeF, wspólny dla każdej integracji. KSeF Import trzyma własny bufor poniżej tych progów i pilnuje ich osobno dla każdego NIP-u oraz łącznie dla całej infrastruktury.
System czeka dokładnie tyle, ile wskazuje odpowiedź KSeF, i ponawia próbę przy najbliższym cyklu – zwykle nie musisz nic ręcznie ponawiać, a faktura dochodzi z niewielkim opóźnieniem.
Co dokładnie oznacza limit zapytań API KSeF
Krajowy System e-Faktur udostępnia dane przez API z twardo określonymi progami – to nie „awaria”, tylko zabezpieczenie infrastruktury Ministerstwa Finansów przed przeciążeniem. Każde narzędzie łączące się z KSeF (nie tylko KSeF Import) działa w tych samych granicach.
| Rodzaj zapytania | Limit KSeF (dokumentowany) |
|---|---|
| Metadane faktur (lista, wyszukiwanie) | 8/s · 16/min · 20/godz. |
| Eksport paczek faktur | 8/s · 16/min · 20/godz. |
| Pobranie pojedynczej faktury | 8/s · 16/min · 64/godz. |
Limity liczą się dla pary kontekst (NIP) + adres IP, w przesuwającym się oknie czasowym – system sprawdza, ile zapytań padło w ostatnich 60 minutach, 60 sekundach i ostatniej sekundzie, a blokada startuje przy pierwszym przekroczeniu któregokolwiek progu. Po przekroczeniu KSeF zwraca kod HTTP 429 z nagłówkiem Retry-After – liczbą sekund, po której wolno spróbować ponownie.
Dlaczego to dotyczy Ciebie, nawet bez pisania kodu
Ręczne przeglądanie kilku faktur w portalu Ministerstwa Finansów praktycznie nigdy nie zbliży Cię do tych progów. Limit zaczyna mieć znaczenie dopiero, gdy jakieś narzędzie pobiera dane automatycznie i regularnie – a o to właśnie chodzi w automatycznym pobieraniu faktur z KSeF: system sam odpytuje API według harmonogramu, bez klikania w portalu.
Im więcej faktur i NIP-ów obsługujesz, tym częściej harmonogram sięga po nowe dane – a to oznacza więcej zapytań w tym samym oknie czasowym. Dlatego pilnowanie limitu nie jest opcją, tylko warunkiem, żeby automatyzacja w ogóle działała stabilnie.
Zobacz, jak KSeF Import pobiera faktury kosztowe i układa je w gotowy arkusz.
Jak KSeF Import pilnuje limitu za Ciebie
Zamiast czekać na błąd 429 i dopiero wtedy reagować, KSeF Import rezerwuje zapytania z góry w trzech niezależnych warstwach:
| Warstwa | Co pilnuje |
|---|---|
| Bufor per NIP | Osobny licznik godzinowy dla każdego NIP-u, z zapasem poniżej najbardziej ograniczającego progu MF (np. 60/godz. zamiast dokumentowanych 64, 18/godz. zamiast 20) – to próg godzinowy pilnowany jest na bieżąco, progi sekundowy i minutowy z tabeli wyżej pozostają zapasem |
| Globalny bufor per IP | Łączny licznik dla całej infrastruktury – bezpiecznik na wypadek nieudokumentowanego limitu na sam adres IP, gdy wiele NIP-ów synchronizuje się jednocześnie |
| Zamek synchronizacji per NIP | Blokuje kolizję: ręczne odświeżenie NIP-u nie wystartuje równolegle z zaplanowaną synchronizacją tego samego NIP-u |
Zanim padnie zapytanie do KSeF, system sprawdza, czy w oknie czasowym jest jeszcze miejsce – zarówno w buforze NIP-u, jak i w buforze globalnym. Jeśli globalny bufor akurat jest pełny mimo wolnego miejsca na NIP, rezerwacja NIP-u wraca do puli, żeby nie przepadła na próżno.
Co się dzieje, gdy limit i tak zostanie osiągnięty
Bufor poniżej oficjalnego limitu redukuje ryzyko, ale go nie zeruje – przy bardzo aktywnym NIP-ie albo chwilowym spiętrzeniu zapytań 429 może i tak się pojawić. Wtedy w tle dzieje się to:
-
1
Odczekanie z Retry-After
System nie zgaduje – czeka dokładnie tyle sekund, ile podał KSeF w odpowiedzi, zanim spróbuje ponownie.
-
2
Ponowna próba, maksymalnie trzy razy na paczkę
Jeśli kolejna próba znów trafi w 429, system ponawia jeszcze dwukrotnie w ramach tej samej paczki zanim odłoży resztę na później.
-
3
Krótkie oczekiwanie na wolny slot
System nie czeka bezczynnie w nieskończoność – najwyżej 15 sekund przy pobieraniu treści faktur i do 60 sekund przy odpytywaniu o nowe dokumenty. Jeśli w tym czasie limit się nie zwolni, bieżąca paczka jest odkładana.
-
4
Odstąpienie i powrót po godzinie
Odłożona paczka wraca do kolejki automatycznie po około godzinie – bez ręcznego ponawiania. Jeśli limit utrzymuje się mimo kilku takich prób z rzędu i w żadnej z nich nie pobrano ani jednej nowej faktury, system wycofuje się na dłużej – na 2 godziny – zamiast bez końca dobijać się do tego samego progu.
Jeśli faktury nie pobierają się przez wiele godzin, a nie tylko kilkanaście minut, częstszą przyczyną jest cofnięte uprawnienie certyfikatu, nie limit zapytań – opisujemy to osobno w artykule o błędzie autoryzacji KSeF.
Biuro rachunkowe z wieloma NIP-ami – na co zwrócić uwagę
Limity KSeF liczą się per NIP, więc dziesięć obsługiwanych firm to dziesięć osobnych, niezależnych budżetów zapytań – jeden aktywny NIP nie zabiera limitu innemu. Realne ryzyko pojawia się na poziomie globalnego budżetu współdzielonej infrastruktury, gdy wiele synchronizacji rusza w tym samym momencie.
Dlatego harmonogramy nie startują wszystkie o tej samej sekundzie – pobrania są rozłożone w czasie, a przy planach obsługujących więcej niż jeden NIP każda firma ma dodatkowo własny, niezależny harmonogram (godzina synchronizacji ustawiana osobno per NIP).
Najczęstsze pytania
Krótkie, konkretne odpowiedzi na pytania, które zadają użytkownicy i wyszukiwarki.
Zwykle nie. KSeF Import rezerwuje zapytania z buforem poniżej oficjalnych limitów i pilnuje ich osobno dla każdego NIP-u oraz łącznie dla całej infrastruktury, więc do samego kodu 429 dochodzi rzadko – a gdy już dojdzie, system sam czeka i ponawia próbę.
Nie. Pilnowanie limitów i automatyczne ponawianie działa w tle, niezależnie od Twoich ustawień – jedyne, co konfigurujesz, to certyfikat dla danego NIP-u.
Bezpośrednio nie – każdy NIP ma własny, oddzielny budżet zapytań w KSeF. Ryzyko rośnie tylko na poziomie współdzielonej infrastruktury, gdy wiele synchronizacji startuje jednocześnie, dlatego harmonogramy poszczególnych NIP-ów są rozłożone w czasie zamiast uruchamiać się równo o tej samej porze.
System odpowiada od razu, bez zgadywania: czeka najwyżej 15-60 sekund na wolny slot, a jeśli limit się nie zwolni, odkłada bieżącą paczkę i wraca do niej automatycznie po około godzinie. Dopiero gdy limit utrzymuje się mimo kilku kolejnych prób z rzędu, system wycofuje się na dłużej – na 2 godziny.
Może nim być, jeśli limit utrzymywał się mimo kilku prób z rzędu – wtedy system celowo wycofuje się na 2 godziny, żeby nie dobijać się do tego samego progu. Jeśli przerwa trwa jednak wyraźnie dłużej niż kilka godzin, częstszą przyczyną jest cofnięte uprawnienie certyfikatu albo jego nieważność; sprawdź panel pod kątem czerwonego banera z komunikatem o uprawnieniach.
Inżynier integracji KSeF. Odpowiada za połączenia z API Krajowego Systemu e-Faktur, automatyzacje i parsowanie struktury logicznej FA(3).