Program pokazuje, że sesja wsadowa w Krajowym Systemie e-Faktur (KSeF) zakończyła się statusem 420 i komunikatem „Przekroczony limit faktur w sesji”. Przy wysyłce pojedynczych faktur ta sama sytuacja wygląda inaczej. KSeF odrzuca kolejną fakturę odpowiedzią HTTP 400 z kodem 21155 „Przekroczono dozwoloną liczbę faktur w sesji.”
Oba komunikaty dotyczą liczby faktur w jednej sesji, a nie ich treści. Poniżej znajdziesz limity z dokumentacji MF, przyczyny, sposób ich rozpoznania i kroki, które pozwalają dokończyć wysyłkę. Pozostałe kody opisujemy na stronie z pełną listą kodów błędów KSeF.
Co oznacza kod 420
420 to status całej sesji wsadowej, czyli wysyłki paczki faktur w jednym archiwum ZIP. Program odczytuje go, sprawdzając stan sesji. Oficjalny opis brzmi „Przekroczony limit faktur w sesji”.
W dokumentacji API KSeF 2.0 (repozytorium CIRF) kod 420 ma tylko to jedno znaczenie. Nie ma go wśród statusów pojedynczej faktury ani wśród statusów logowania. Nie myl go z dwoma podobnymi numerami:
- 429 to kod HTTP „Too Many Requests”, czyli zbyt wiele zapytań w krótkim czasie. Opisujemy go w tekście o błędzie 429 w KSeF.
- 425 to status logowania „Uwierzytelnienie unieważnione”. Nie ma nic wspólnego z liczbą faktur.
Dokumentacja MF podaje tylko opis statusu 420. Nie wyjaśnia, czy KSeF przetwarza jakąkolwiek fakturę z takiej sesji. Dlatego przed ponowną wysyłką trzeba to sprawdzić. Kroki opisujemy niżej.
Odpowiednik w sesji interaktywnej: kod 21155
W sesji interaktywnej program wysyła faktury pojedynczo, każdą osobnym żądaniem. Gdy sesja dojdzie do limitu, KSeF odrzuca kolejne żądanie odpowiedzią HTTP 400 z kodem 21155. Szczegóły podają numer sesji i limit: „Sesja o numerze referencyjnym {referenceNumber} osiągnęła dozwolony limit liczby faktur {invoiceLimit}.”
Różnica jest praktyczna. Status 420 dotyczy całej paczki. Kod 21155 dotyczy jednej próby wysyłki. Faktury wysłane wcześniej w tej sesji mają własne statusy i to je trzeba sprawdzić.
Ile wynosi limit
Dokument MF o weryfikacji faktur (weryfikacja-faktury.md) w części „Ograniczenia ilościowe” podaje: najwyżej 10 000 faktur w jednej sesji, interaktywnej i wsadowej.
Dokument o limitach (limity.md) zalicza ten limit do limitów na kontekst. Kontekst to podmiot, w którego imieniu program się zalogował. Limit może być ustawiony dla kontekstu indywidualnie. Dlatego komunikat 21155 podaje konkretną wartość w miejscu {invoiceLimit}. To limit, który obowiązuje w Twoim kontekście.
Inne limity paczki wsadowej
Ta sama część „Ograniczenia ilościowe” podaje limity samej paczki:
- najwyżej 50 części,
- każda część najwyżej 100 MB przed zaszyfrowaniem,
- cała paczka najwyżej 5 GB.
Z tymi limitami wiążą się własne kody. Nie są to statusy sesji, tylko odpowiedzi HTTP 400 na żądanie programu:
- 21161 „Przekroczono dozwoloną liczbę części pakietu.” Paczka ma więcej części, niż pozwala limit.
- 21157 „Nieprawidłowy rozmiar części pakietu.” Dokumentacja podaje tylko opis. Najbliższa opisana reguła to 100 MB na część przed zaszyfrowaniem.
- 21205 „Pakiet nie może być pusty.” Paczka nie zawiera żadnej treści.
Limit czasu na przesłanie paczki
Sesja wsadowa ma też limit czasu. Dokumentacja sesji wsadowej (sesja-wsadowa.md) przewiduje „20 minut na każdy part” i dodaje: „Łączny czas na wysyłkę każdego parta = liczba partów × 20 minut.” Paczka z pięciu części ma więc łącznie 100 minut.
Gdy program nie zdąży, sesja kończy się statusem 440 „Sesja anulowana” ze szczegółem „Przekroczono czas wysyłki”. Próba zamknięcia sesji dostaje wtedy kod 21208 „Czas oczekiwania na requesty upload lub finish został przekroczony.”, ze szczegółem „Sesja anulowana, przekroczony czas wysyłki.” To inny problem niż 420. Opisujemy go w tekście o błędzie 440 w KSeF.
Najczęstsze przyczyny
1. Wszystko w jednej paczce
Program albo skrypt pakuje do jednej sesji wszystko, co czeka na wysyłkę dla danego NIP-u. Przy dużym sprzedawcy może to być więcej niż 10 000 faktur. Rozpoznasz po tym, że 420 pojawia się tylko przy największych wysyłkach, a mniejsze przechodzą bez problemu.
2. Inny limit w Twoim kontekście
Limit może być ustawiony indywidualnie dla kontekstu. Rozpoznasz po komunikacie 21155: jeżeli wartość limitu w szczegółach jest inna niż 10 000, obowiązuje Cię właśnie ona. Program może też odczytać aktualny limit z KSeF. Szczegóły podajemy w części dla programisty.
3. Jedna sesja interaktywna na cały dzień
Program otwiera jedną sesję interaktywną i wysyła do niej faktury, aż dojdzie do limitu. Rozpoznasz po tym, że 21155 pojawia się w środku wysyłki, a wcześniejsze faktury z tej samej sesji przeszły. Przy okazji: czas życia sesji interaktywnej to 12 godzin od jej utworzenia, potem KSeF zamyka ją automatycznie (sesja-interaktywna.md).
Co zrobić krok po kroku
Przy statusie 420 (sesja wsadowa)
- Upewnij się, że to 420. Kody 440 „Sesja anulowana” i 445 „Błąd weryfikacji, brak poprawnych faktur” też dotyczą całej sesji, ale mają inne przyczyny. Drugi z nich opisujemy w tekście o błędzie 445 w KSeF.
- Sprawdź, co się stało z fakturami z tej sesji. Przejrzyj listę faktur sesji i ich statusy. Faktura ze statusem 200 „Sukces” już jest w KSeF i nie wysyłasz jej ponownie.
- Podziel pozostałe faktury na kilka paczek. Każda paczka wyraźnie poniżej limitu. Każdą wyślij w osobnej sesji.
- Nie wysyłaj dwa razy tego, co przeszło. Faktura z tym samym NIP-em sprzedawcy, rodzajem i numerem zostanie odrzucona jako duplikat, kodem 440.
- Odbierz UPO dla każdej sesji. UPO, czyli Urzędowe Poświadczenie Odbioru, powstaje po zamknięciu sesji. Przy kilku sesjach będzie kilka UPO.
Przy kodzie 21155 (sesja interaktywna)
- Zamknij sesję, która doszła do limitu. Dopiero po zamknięciu KSeF wygeneruje dla niej UPO.
- Otwórz nową sesję. Wyślij w niej fakturę, która dostała 21155, i wszystkie kolejne. Ta faktura dostała odmowę, więc nie trafiła do starej sesji.
- Sprawdź statusy faktur ze starej sesji. Każda ze statusem 200 „Sukces” jest w KSeF.
- Jeżeli 21155 wraca regularnie, zmień sposób wysyłki. Program powinien otwierać nową sesję, zanim dojdzie do limitu. To zadanie dla dostawcy programu.
Jeżeli podział na sesje Ci nie wystarcza i potrzebujesz innego limitu dla swojego kontekstu, zapytaj MF przez formularz zgłoszeniowy.
Jak temu zapobiec
- Dziel z zapasem. Planuj paczki wyraźnie mniejsze niż limit, a nie „na styk”.
- Nie dziel na zbyt drobne kawałki. Otwieranie sesji ma własne limity zapytań, liczone dla pary kontekst i adres IP (limity-api.md). Sesję wsadową otworzysz najwyżej 10 razy na sekundę, 20 razy na minutę i 60 razy na godzinę. Sesję interaktywną: 10 razy na sekundę, 30 razy na minutę i 120 razy na godzinę. Po przekroczeniu KSeF odpowiada kodem 429.
- Pamiętaj o czasie. Mniejsza paczka szybciej się przesyła. Gdy sesja zostanie anulowana, ponawiasz mniej faktur.
- Otwieraj nowe sesje interaktywne regularnie. Nie trzymaj jednej sesji przez cały dzień wysyłek.
My sami dzielimy duże wolumeny na mniejsze sesje. W lipcu 2026 r. około 970 faktur jednego klienta poszło u nas w 14 sesjach wsadowych, a UPO odebraliśmy dla wszystkich. Co jeszcze wychodzi przy dużych paczkach, opisujemy w tekście Tysiąc faktur miesięcznie w KSeF: co naprawdę się psuje.
Dla programisty
Limit dla kontekstu odczytasz z GET /limits/context. W sesji interaktywnej 21155 przychodzi jako wyjątek HTTP 400 na POST /sessions/online/{referenceNumber}/invoices, z polami ExceptionCode, ExceptionDescription i Details. Wartość limitu jest w Details. W sesji wsadowej 420 to kod statusu w odpowiedzi GET /sessions/{referenceNumber}, a 21161, 21157 i 21205 to wyjątki HTTP 400 dotyczące pakietu. Licz faktury przed zbudowaniem ZIP-a i dziel je po stronie klienta: limit z /limits/context na sesję, 50 części, 100 MB na część przed szyfrowaniem, 5 GB na pakiet. Pilnuj czasu: 20 minut na każdą część. Po jego przekroczeniu zamknięcie sesji zwraca 21208.
Wysyłasz duże paczki faktur? FakturaFlow wysyła pojedyncze faktury i duże paczki w sesjach wsadowych, a UPO pobiera sam. Każdy błąd KSeF pokazuje po polsku, z informacją, co poprawić. Gdy KSeF jest chwilowo niedostępny, sam ponawia wysyłkę, a faktura czeka. Działa obok Twojego programu księgowego, nie zamiast niego. Zobacz, jak działa FakturaFlow.
Podsumowanie
Status 420 w sesji wsadowej i kod 21155 w sesji interaktywnej znaczą, że w jednej sesji jest więcej faktur, niż pozwala limit. Dokumentacja MF podaje 10 000, a wartość dla Twojego kontekstu podaje komunikat 21155. Sprawdź, które faktury już przeszły, podziel resztę na mniejsze sesje i nie wysyłaj ponownie tego, co KSeF przyjął. Pozostałe kody opisuje pełna lista 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.