Błąd 429 w KSeF: „Too Many Requests”, czyli za dużo zapytań naraz

Wysyłka do Krajowego Systemu e-Faktur (KSeF) staje w połowie. W historii wysyłki albo w logu programu pojawia się kod HTTP 429 z opisem „Too Many Requests”. Czasem obok jest zdanie po polsku, na przykład takie, jakie podaje dokumentacja Ministerstwa Finansów: „Przekroczono limit 20 żądań na minutę. Spróbuj ponownie po 30 sekundach.”

Ta strona wyjaśnia, co ten kod znaczy, dlaczego nie oznacza błędu w fakturze i co zrobić, żeby wysyłka poszła dalej. Jeśli szukasz innego kodu, zajrzyj na pełną listę kodów błędów KSeF.

Co oznacza kod 429

429 to kod odpowiedzi HTTP. Nie jest to status faktury, status sesji ani status logowania. W tabelach statusów KSeF takiego numeru nie ma. Dokumentacja limitów API mówi wprost, że po przekroczeniu limitu „zwracany jest kod HTTP 429 Too Many Requests”.

KSeF ogranicza liczbę zapytań, które program może wysłać. Limit liczy się dla pary: kontekst i adres IP. Kontekst to najczęściej NIP, w imieniu którego program jest zalogowany. Gdy program przekroczy limit, KSeF na chwilę go blokuje. Blokada jest tymczasowa, a jej długość system ustala dynamicznie. Liczbę sekund, którą trzeba odczekać, KSeF podaje w nagłówku odpowiedzi Retry-After.

Najważniejsze: 429 mówi o tempie, w jakim program rozmawia z KSeF. Nie mówi nic o treści faktury.

Jakie są limity

Komunikat o 20 żądaniach na minutę to tylko przykład z dokumentacji. Każda operacja ma własny limit na sekundę, na minutę i na godzinę. Liczy się je w oknach przesuwnych, czyli zawsze za ostatnią sekundę, minutę i godzinę, a nie za pełną godzinę zegarową. Tak wyglądają limity operacji ważnych przy wysyłce (stan z 14 września 2026 r., dokumentacja limitów API KSeF):

Kilka rzeczy, które z tego wynikają:

• Wysyłka faktura po fakturze ma sufit. W sesji interaktywnej program wyśle najwyżej 30 faktur na minutę i 180 na godzinę. Pięćset faktur wysyłanych pojedynczo zajmie więc prawie trzy godziny.
• Sesja wsadowa tego sufitu nie ma. Przesyłanie części paczki nie ma limitu. Jedna sesja wsadowa mieści do 10 000 faktur.
• Pobieranie UPO przez link nie ma limitu. Limitowane są natomiast zapytania o status.
• Limity zamykania sesji są nowe. Doszły w wersji 2.8.0 API, na produkcji od 23 września 2026 r. MF ustawiło je dwa razy wyżej niż limity otwierania sesji.
• Środowisko DEMO ma takie same limity jak produkcja. Na środowisku TEST są dziesięć razy wyższe.

Czy faktura dotarła do KSeF?

429 to odmowa przyjęcia zapytania. Jeśli przyszło przy wysyłce faktury, ta faktura nie dostała numeru KSeF. Trzeba ją wysłać jeszcze raz, po odczekaniu.

To inna sytuacja niż zerwane połączenie, po którym nie wiadomo, czy faktura dotarła. Nawet gdyby faktura trafiła do KSeF wcześniej, ponowna wysyłka faktury z tym samym numerem nie utworzy drugiej. Według dokumentacji MF „KSeF wykrywa duplikaty faktur globalnie” i odpowiada kodem 440. Więcej o tym w tekście o błędzie 440 w KSeF.

Najczęstsze przyczyny

1. Faktury wysyłane pojedynczo, każda osobnym zapytaniem

W sesji interaktywnej każda faktura to osobne zapytanie. Do tego dochodzą logowanie, otwarcie i zamknięcie sesji oraz sprawdzanie statusów. Przy kilku fakturach to bez znaczenia. Przy kilkuset program szybko dochodzi do limitu 30 faktur na minutę. Jeszcze szybciej, gdy dla każdej faktury loguje się od nowa i otwiera osobną sesję, bo otwarcie sesji ma limit 120 na godzinę.

Jak rozpoznać: pierwsze faktury z dużej wysyłki przechodzą, a 429 pojawia się w jej trakcie. Zwykle przy wysyłce całego miesiąca dla jednego klienta.

2. Zbyt częste sprawdzanie statusów i UPO

Po wysłaniu program pyta KSeF, czy faktura została przyjęta. Potem pobiera UPO, czyli Urzędowe Poświadczenie Odbioru. Samo pobranie UPO przez link nie ma limitu, ale zapytania o status sesji i faktur już tak. Program, który co chwilę odpytuje każdą fakturę osobno, zużywa limit bez potrzeby.

Jak rozpoznać: sama wysyłka przeszła, a 429 pojawia się przy odświeżaniu statusów.

3. Ponawianie bez czekania

Część programów po błędzie od razu próbuje jeszcze raz. Przy 429 to nic nie daje. Dopóki trwa blokada, kolejne zapytania też wracają z 429.

Jak rozpoznać: w logu widać serię kodów 429 w odstępach kilku sekund albo krótszych.

4. Kilka wysyłek naraz dla tego samego klienta

Dwie osoby w biurze uruchamiają wysyłkę dla tej samej firmy w tym samym czasie. Albo jedna wysyłka jeszcze trwa, a ktoś startuje drugą. Jeśli obie idą w tym samym kontekście i z tego samego adresu IP, dzielą jeden limit. Tak jest na przykład wtedy, gdy obie osoby pracują w tym samym programie w chmurze.

Jak rozpoznać: 429 pojawia się tylko wtedy, gdy wysyłki dla jednego NIP-u nakładają się w czasie.

Co zrobić krok po kroku

1. Nie poprawiaj faktury. 429 nie dotyczy jej treści. Edycja niczego nie naprawi, a może wprowadzić nowy błąd.
2. Sprawdź, ile KSeF każe czekać. Wartość z nagłówka Retry-After jest w sekundach. Część programów pokazuje ją w komunikacie albo w logu. Jeśli jej nie widzisz, odczekaj kilka minut.
3. Sprawdź, które faktury przeszły. W historii wysyłki porównaj faktury z numerem KSeF i bez niego. Ponownie wysyłasz tylko te bez numeru.
4. Wyślij resztę po odczekaniu. Jeśli program ma wysyłkę wsadową (paczkami), użyj jej przy większej liczbie faktur.
5. Nie uruchamiaj równoległych wysyłek dla tego samego klienta. Poczekaj, aż jedna się skończy.
6. Jeśli 429 wraca mimo czekania, zgłoś to dostawcy programu. Podaj datę i godzinę, liczbę faktur w wysyłce i treść komunikatu. To program decyduje, jak często pyta KSeF, więc tylko jego dostawca może to zmienić.

Jak temu zapobiec

• Duże wolumeny wysyłaj w sesji wsadowej. Program przesyła wtedy jedno archiwum z wieloma fakturami, w zaszyfrowanych częściach, zamiast setek osobnych zapytań. Limit 180 faktur na godzinę go nie dotyczy. Opis MF: sesja wsadowa. Jak to wygląda w biurze, pokazujemy w tekstach jak wysyłać faktury do KSeF hurtowo oraz tysiąc faktur miesięcznie w KSeF.
• Jedna wysyłka na klienta naraz. Ustal w biurze, kto wysyła dla danej firmy.
• Zapytaj dostawcę o dwie rzeczy. Czy program sam odczekuje czas z Retry-After? Czy ma tryb wsadowy dla większych paczek?

Dla programistów

Traktuj 429 jako błąd przejściowy, a nie odrzucenie faktury. Odczytaj nagłówek Retry-After (wartość w sekundach) i nie wysyłaj kolejnego zapytania w tym kontekście przed jego upływem. Gdy nagłówka brak, stosuj rosnące odstępy (exponential backoff) z losowym rozrzutem i górną granicą liczby prób. Nigdy nie ponawiaj w ciasnej pętli, bo w czasie blokady każde zapytanie wraca z 429. Jedną sesję interaktywną wykorzystuj do wielu faktur, zamiast otwierać sesję na każdą fakturę. Przy większych wolumenach przejdź na sesję wsadową. Statusy odpytuj rzadziej, z rosnącym odstępem, a kolejkę rozkładaj w czasie. Pamiętaj, że limit liczy się dla pary kontekst i adres IP w oknach przesuwnych, więc kilka procesów wysyłających z jednego serwera dla jednego NIP-u dzieli ten sam limit. Zachowanie przy limitach sprawdzaj na DEMO, które ma limity produkcyjne. TEST ma limity dziesięć razy wyższe i ukryje problem. Nie wpisuj limitów na sztywno, bo się zmieniają: w wersji 2.8.0 API doszły osobne limity dla zamykania sesji. Aktualne wartości są w pliku limity-api.md w repozytorium ksef-docs.

Z naszej praktyki

Nasza zasada jest prosta: 429 nie jest powodem, żeby ruszać fakturę. Ważniejsze jest jednak, żeby do limitu w ogóle nie dochodzić. Do października 2026 r. wysłaliśmy do produkcyjnego KSeF ponad 1 700 faktur, większość w sesjach wsadowych. W lipcu 2026 r. dla jednego klienta poszło w ten sposób około 970 faktur w 14 sesjach. Dla wszystkich odebraliśmy UPO. Czternaście sesji to dużo mniej zapytań niż prawie tysiąc osobnych wysyłek.

Wysyłasz setki faktur miesięcznie? FakturaFlow wysyła pojedyncze faktury i duże paczki w sesjach wsadowych, a UPO pobiera sam. Przed wysyłką sprawdza każdą fakturę według reguł FA(3), więc wiele odrzuceń w ogóle nie dochodzi do KSeF. Każdy błąd KSeF pokazuje po polsku, z informacją, co poprawić. Działa obok Twojego programu księgowego, nie zamiast niego. Załóż konto i sprawdź.

Podsumowanie

Kod 429 „Too Many Requests” znaczy, że program pytał KSeF zbyt często, a nie że faktura jest zła. Odczekaj czas z nagłówka Retry-After i wyślij ponownie tylko faktury bez numeru KSeF. Wysyłając faktury pojedynczo, program wyśle najwyżej 180 na godzinę, więc przy dużych wolumenach wysyłaj w sesji wsadowej. Inne kody opisujemy na pełnej liście kodów błędów KSeF.

Stan na październik 2026 r. Opis na podstawie dokumentacji API KSeF 2.0 (wersja 2.8). Kody i komunikaty mogą się zmienić wraz z nowymi wersjami API.