Program pokazuje kod 21405 i komunikat „Błąd walidacji danych wejściowych.”, a obok krótki szczegół z walidatora. Szczegół bywa po angielsku, na przykład 'encryption' must not be empty. To właśnie on mówi, co poszło nie tak. Krajowy System e-Faktur (KSeF) nie przyjął żądania, które wysłał Twój program.
Tu dowiesz się, jak czytać szczegół błędu 21405, kto może go naprawić i co przekazać dostawcy programu. Inne kody opisujemy na pełnej liście kodów błędów KSeF.
Co oznacza kod 21405
Kod 21405 to kod wyjątku, a nie status faktury. KSeF zwraca go od razu, w odpowiedzi HTTP 400. Odpowiedź ma trzy pola: ExceptionCode (czyli 21405), ExceptionDescription z opisem „Błąd walidacji danych wejściowych.” oraz Details z treścią błędu z walidatora.
Według historii zmian API KSeF to uniwersalny kod walidacji, wspólny dla wszystkich punktów API. Walidator sprawdza, czy żądanie programu ma wymagane pola i czy mają one właściwy format. Jeżeli nie, KSeF odpowiada kodem 21405 i zwraca komunikat walidatora w szczegółach.
Błąd może więc przyjść na każdym etapie pracy programu z KSeF. Specyfikacja wymienia go między innymi przy otwieraniu sesji interaktywnej i przy wysyłce faktury w tej sesji.
Opis „Błąd walidacji danych wejściowych.” jest zawsze ten sam. Całą informację niesie szczegół. Bez niego nie da się powiedzieć, co jest nie tak.
Czym 21405 różni się od 450 i 430
Te trzy kody łatwo pomylić, bo wszystkie mówią o weryfikacji lub walidacji. Różnią się tym, co KSeF sprawdzał i kiedy odpowiedział.
- 21405 dotyczy żądania programu. KSeF odrzuca je od razu. Jeżeli błąd przyszedł przy wysyłce, faktura nie weszła do przetwarzania i nie ma żadnego statusu.
- 430 to status faktury: „Błąd weryfikacji pliku faktury”. KSeF przyjął fakturę do przetwarzania, a potem weryfikacja samego pliku zakończyła się błędem. Dokumentacja MF nie podaje przyczyn. Opis: błąd 430 w KSeF.
- 450 to status faktury: „Błąd weryfikacji semantyki dokumentu faktury”. Plik jest poprawny technicznie, ale jego treść łamie zasady FA(3). Opis: błąd 450 w KSeF.
Prosta reguła: kod pięciocyfrowy zaczynający się od 21 dotyczy tego, jak program rozmawia z KSeF. Kod trzycyfrowy przy fakturze może dotyczyć samej faktury.
Najczęstsze przyczyny
1. Puste albo brakujące pole w żądaniu
Program wysyła żądanie, w którym brakuje wymaganego pola albo pole jest puste. Tak było u nas: przy otwieraniu sesji zabrakło danych szyfrowania. Opisujemy to niżej, w części „Z naszej praktyki”.
Jak rozpoznać: błąd pojawia się przy każdej próbie, w tym samym miejscu, bez względu na fakturę. Szczegół wskazuje pole po nazwie. Zwykle wychodzi od pierwszej wysyłki po zmianie w programie, na przykład w nowej integracji.
2. Program nie nadąża za nową wersją API
MF publikuje nowe wersje API KSeF i opisuje zmiany w historii zmian. Nowa wersja trafia najpierw na środowiska TEST i DEMO, a potem na produkcję. Przykład: wersja 2.8.0 weszła na TEST 14 września 2026 r., na DEMO 15 września 2026 r., a na produkcję 23 września 2026 r. Jeżeli nowa wersja zmienia pola żądania, a program nie został zaktualizowany, walidator może odrzucić żądanie w starym kształcie.
Jak rozpoznać: błąd pojawia się nagle, od konkretnego dnia, choć po Twojej stronie nic się nie zmieniło. Dotyka wtedy zwykle wszystkich użytkowników tej samej wersji programu.
3. Wartość w złym formacie
Pole jest obecne, ale jego wartość nie pasuje do oczekiwanego formatu. Może to być wartość wyliczona przez program albo coś, co wpisano ręcznie, na przykład parametr wyszukiwania przy pobieraniu faktur.
Jak rozpoznać: błąd pojawia się tylko przy części operacji albo danych. Szczegół wskazuje pole, którego dotyczy.
Pokrewne kody z własnym opisem
Niektóre problemy z żądaniem mają osobne kody. Przy wysyłce faktury to 21402 („Nieprawidłowy rozmiar pliku.”) i 21403 („Nieprawidłowy skrót pliku.”). Pierwszy z nich opisujemy w tekście o błędzie 21402 w KSeF. Przy otwieraniu sesji to 21470, czyli nieznany lub wycofany klucz publiczny MF: błąd 21470 w KSeF.
Co zrobić krok po kroku
-
Przeczytaj szczegół, nie tylko opis. Szczegół znajdziesz zwykle w historii wysyłki albo w dzienniku programu. Jeżeli program pokazuje tylko kod, poszukaj widoku szczegółów lub logu.
-
Ustal, na jakim etapie padł błąd. Może to być otwarcie sesji, wysyłka faktury, zamknięcie sesji albo pobieranie statusu lub UPO (Urzędowe Poświadczenie Odbioru). Od tego zależy następny krok.
-
Sprawdź, czy faktura jest w KSeF. Jeżeli błąd przyszedł przy otwarciu sesji albo przy wysyłce faktury, faktura do KSeF nie trafiła. Po poprawce wyślesz ją bez obawy o duplikat. Jeżeli błąd przyszedł później, na przykład przy pobieraniu statusu, faktura mogła już zostać przyjęta. Wtedy najpierw sprawdź jej status, a dopiero potem wysyłaj ponownie.
-
Nie poprawiaj faktury na ślepo. Żądanie buduje program, nie Ty. Jeżeli szczegół nie wskazuje czegoś, co wpisano ręcznie, zmiana faktury nic nie da. Ponowna wysyłka bez zmiany w programie zwykle kończy się tym samym błędem.
-
Sprawdź, czy program jest zaktualizowany. Jeżeli błąd pojawił się nagle, poszukaj aktualizacji albo komunikatu dostawcy.
-
Zgłoś błąd dostawcy programu. Zwykle tylko on może go naprawić. Przekaż mu:
- pełny tekst szczegółu, skopiowany słowo w słowo, bez tłumaczenia i skracania,
- datę i godzinę błędu,
- etap, na którym padł (otwarcie sesji, wysyłka, pobieranie),
- numer referencyjny sesji, jeśli program go pokazuje,
- wersję programu i środowisko (produkcja, DEMO, TEST).
Sam kod 21405 bez szczegółu niewiele dostawcy powie.
-
Do MF pisz tylko w ostateczności. Ma to sens wtedy, gdy dostawca wykaże, że żądanie jest zgodne ze specyfikacją, a KSeF i tak je odrzuca. Użyj formularza MF albo adresu jpk.helpdesk@mf.gov.pl.
Jak temu zapobiec
Aktualizuj program na bieżąco. Gdy MF zapowiada nową wersję API, sprawdź, czy dostawca programu wydał do niej poprawkę. Po aktualizacji przejrzyj historię pierwszych wysyłek.
Dla programisty. Porównaj treść żądania ze specyfikacją OpenAPI w repozytorium ksef-docs (plik open-api.json). Sprawdź pola wymagane, typy, formaty i dozwolone wartości dla punktu API, na którym padł błąd. Najlepiej waliduj żądania względem tej specyfikacji w testach, zanim trafią do KSeF. Loguj pełną treść pola Details razem z punktem API i czasem, ale bez tokenu KSeF i kluczy. Upewnij się, że każda wartość jest gotowa przed serializacją do JSON: u nas zawiodło brakujące await przy funkcji asynchronicznej. Śledź historię zmian API i testuj nowe wersje na środowisku TEST lub DEMO, bo trafiają tam przed produkcją.
Z naszej praktyki
W kwietniu 2026 r. budowaliśmy pierwszą integrację z KSeF 2.0. Otwarcie sesji interaktywnej kończyło się kodem 21405 i szczegółem 'encryption' must not be empty.
Przyczyna leżała w naszym programie. Żądanie otwarcia sesji szło bez bloku danych szyfrowania. Funkcja, która przygotowuje klucz i wektor IV, działa asynchronicznie, a program nie poczekał na jej wynik. Klucz i IV były więc puste, a KSeF słusznie odmówił. Naprawa zajęła jedną linijkę kodu.
Z tej historii płyną dwie rzeczy przydatne każdemu biuru. Po pierwsze, szczegół wskazał pole wprost: encryption. Po drugie, przyszedł po angielsku, więc nie tłumacz go na własną rękę, tylko przekaż dostawcy słowo w słowo. Wniosek główny: 21405 to błąd żądania, a nie faktury. Naprawić go zwykle może tylko autor programu.
FakturaFlow pokazuje każdy błąd KSeF po polsku, z informacją, co poprawić. Po zapisaniu tokenu KSeF lub certyfikatu od razu loguje się do KSeF i mówi, czy połączenie działa. Przed wysyłką sprawdza każdą fakturę według reguł FA(3). Działa obok Twojego programu księgowego, nie zamiast niego. Zobacz, jak działa FakturaFlow.
Podsumowanie
Kod 21405 oznacza, że KSeF odrzucił żądanie programu, a nie treść faktury. Najważniejszy jest szczegół z walidatora, bo wskazuje pole. Naprawić to może zwykle tylko dostawca programu, więc przekaż mu pełny tekst szczegółu i godzinę błędu. Pozostałe 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.