Krajowy System e-Faktur (KSeF) odrzucił wysyłkę faktury kodem 21402 i opisem „Nieprawidłowy rozmiar pliku”. Szczegół brzmi: „Długość treści nie zgadza się z rozmiarem pliku”. Bliźniaczy kod 21403 ma opis „Nieprawidłowy skrót pliku” i szczegół „Skrót treści nie zgadza się ze skrótem pliku”.
Dobra wiadomość: oba kody mówią o liczbach kontrolnych, które program dołącza do faktury, a nie o jej treści. Poniżej wyjaśniamy mechanizm, przyczyny i kroki naprawy. Pozostałe kody opisujemy na stronie z pełną listą kodów błędów KSeF.
Co oznaczają kody 21402 i 21403
To kody wyjątków z rodziny 21xxx, zwracane razem z błędem HTTP 400. Nie są statusem faktury, statusem sesji ani statusem logowania. Pojawiają się w odpowiedzi na wysłanie faktury w sesji interaktywnej, czyli w tej, w której faktury idą pojedynczo.
| Kod | Opis MF | Szczegół |
|---|---|---|
| 21402 | „Nieprawidłowy rozmiar pliku.” | „Długość treści nie zgadza się z rozmiarem pliku.” |
| 21403 | „Nieprawidłowy skrót pliku.” | „Skrót treści nie zgadza się ze skrótem pliku.” |
Skąd KSeF wie, że coś się nie zgadza
Faktura nie trafia do KSeF jako zwykły plik. Program szyfruje plik XML kluczem AES wygenerowanym dla sesji. Do zaszyfrowanej faktury dołącza cztery dane kontrolne:
- rozmiar pliku XML przed zaszyfrowaniem,
- skrót tego pliku,
- rozmiar pliku po zaszyfrowaniu,
- skrót pliku zaszyfrowanego.
Skrót to rodzaj odcisku palca pliku, liczony algorytmem SHA-256. Zmiana choćby jednego bajtu daje zupełnie inny skrót. Według dokumentu „Weryfikacja faktury” KSeF porównuje skrót i rozmiar faktury oraz faktury zaszyfrowanej z danymi przesłanymi przez program. Niezgodny rozmiar daje 21402, niezgodny skrót daje 21403. Komunikat nie mówi, która para się nie zgadza: ta sprzed szyfrowania czy ta po nim.
Skutek dla biura: KSeF odrzucił żądanie wysyłki. Faktura nie trafiła do sesji i nie dostała numeru KSeF. Jej treści nikt jeszcze nie oceniał.
Czyj to błąd
Te cztery dane wylicza program, nie Ty. Jeśli się nie zgadzają, program policzył je z innej wersji pliku, niż wysłał, albo policzył je źle. To błąd po stronie dostawcy oprogramowania. Treść faktury jest wtedy zwykle w porządku. Pewność będzie jednak dopiero po poprawnej wysyłce, bo dopiero wtedy KSeF ją sprawdzi.
Najczęstsze przyczyny
Dokumentacja MF nie wymienia przyczyn tych kodów. Poniżej nasze wnioski z samego mechanizmu. Uporządkowaliśmy je według tego, które faktury dotykają, bo to najszybszy sposób rozpoznania.
1. Plik zmieniony po policzeniu skrótu (wszystkie faktury)
Program policzył skrót i rozmiar, a potem jeszcze raz przetworzył plik. Typowe zmiany to zamiana znaków końca linii (Windows zapisuje je inaczej niż Linux), dodanie znacznika BOM na początku pliku, ponowne zakodowanie tekstu albo sformatowanie XML-a wcięciami. Dla człowieka plik wygląda tak samo. Dla skrótu to inny plik.
Jak rozpoznać: błąd dotyczy każdej faktury, często od dnia aktualizacji programu albo zmiany jego konfiguracji.
2. Polskie litery liczone jako znaki, a nie bajty (faktury z polskimi znakami)
Rozmiar pliku to liczba bajtów. W kodowaniu UTF-8 litera „a” zajmuje jeden bajt, a „ą” czy „ł” dwa. Program, który liczy znaki zamiast bajtów, poda za mały rozmiar przy każdej fakturze z polską literą.
Jak rozpoznać: faktury bez polskich znaków przechodzą. Kod 21402 dostają te, w których nazwie nabywcy, adresie albo pozycji jest „ą”, „ę”, „ł” czy „ż”.
3. Rozmiar zaszyfrowanego pliku wyliczony wzorem (mniej więcej co szesnasta faktura)
Szyfrowanie AES-256-CBC z dopełnieniem PKCS#7 wydłuża plik do pełnych bloków po 16 bajtów. Gdy długość pliku XML jest dokładnie wielokrotnością 16, dopełnienie dodaje cały dodatkowy blok. Program, który nie mierzy zaszyfrowanego pliku, tylko wylicza jego rozmiar uproszczonym wzorem, pomyli się właśnie wtedy.
Jak rozpoznać: błąd wraca przy pojedynczych, na pozór przypadkowych fakturach, statystycznie przy mniej więcej co szesnastej. Podobny wzorzec przy innym kodzie opisujemy w tekście o błędzie 435 w KSeF. Tam winne było samo szyfrowanie, a nie dane kontrolne.
4. Dane w złym formacie (wszystkie faktury w nowej integracji)
Skrót ma być zapisany w Base64. Zapis szesnastkowy albo skrót policzony z tekstu zamiast z bajtów pliku nie przejdzie. Taki błąd formatu może też skończyć się ogólnym kodem walidacji, opisanym w tekście o błędzie 21405 w KSeF. Podobnie jest z rozmiarem. Zaszyfrowaną fakturę program przesyła jako tekst Base64, który jest o około jedną trzecią dłuższy niż same bajty. Długość tego tekstu to nie jest rozmiar pliku.
Jak rozpoznać: nie przechodzi żadna faktura, od pierwszej próby. To typowe dla świeżo napisanej integracji.
Co zrobić krok po kroku
- Nie poprawiaj treści faktury. Kwoty, NIP-y i nazwy nie są przyczyną. Zmiana nazwy towaru tylko po to, żeby ominąć polskie litery, ukryje błąd programu, ale go nie usunie.
- Nie ponawiaj wysyłki w kółko. Bez poprawki program policzy dane kontrolne tak samo, więc wynik też będzie ten sam.
- Ustal wzorzec. Sprawdź, czy błąd dotyczy wszystkich faktur, tylko tych z polskimi znakami, czy pojedynczych, przypadkowych. Zanotuj, od kiedy występuje i czy zbiegł się z aktualizacją programu.
- Zgłoś błąd dostawcy programu. Podaj kod (21402 albo 21403), szczegół, godzinę, numer referencyjny sesji, numer faktury i wzorzec z kroku 3. Dołącz plik XML, jeśli program pozwala go zapisać.
- Jeśli faktura jest pilna, wyślij ją inną drogą. Bezpłatna Aplikacja Podatnika KSeF pozwala wczytać pojedynczy plik XML faktury i wysłać go ręcznie. Dane kontrolne policzy wtedy aplikacja MF. Potem oznacz w swoim programie, że faktura jest już w KSeF. Jej ponowna wysyłka po poprawce skończy się kodem 440 „Duplikat faktury”.
- Kiedy pisać do MF. Tylko wtedy, gdy dostawca pokaże, że dane kontrolne policzono z dokładnie tych bajtów, które wysłano, a błąd wraca. Zgłoszenie złożysz przez formularz MF albo na adres jpk.helpdesk@mf.gov.pl.
Jak temu zapobiec
- Po każdej aktualizacji programu wyślij najpierw jedną fakturę z polskimi znakami. Gdy przejdzie, wysyłaj resztę.
- Nie zmieniaj plików, które program przygotował do wysyłki. Każda zmiana po policzeniu skrótu kończy się kodem 21403 albo 21402.
Dla programisty
Mierz i haszuj dokładnie te bajty, które wysyłasz w POST /sessions/online/{referenceNumber}/invoices. Zbuduj XML, zakoduj go raz do UTF-8 bez BOM i od tej chwili pracuj tylko na tej tablicy bajtów. invoiceSize to jej długość w bajtach, a invoiceHash to SHA-256 z tych bajtów, zapisany w Base64, nie w hex. Te same bajty zaszyfruj AES-256-CBC z PKCS#7 kluczem i IV sesji. encryptedInvoiceSize i encryptedInvoiceHash policz z wyniku szyfrowania, zanim zakodujesz go do Base64 w encryptedInvoiceContent. Rozmiaru szyfrogramu nie wyliczaj wzorem, tylko go zmierz. Po policzeniu skrótów niczego już nie normalizuj: żadnej zmiany końców linii, formatowania ani kodowania.
Potrzebujesz drugiej drogi do KSeF? FakturaFlow wysyła do KSeF pojedyncze faktury i duże paczki w sesjach wsadowych, a UPO pobiera sam. Każdy błąd zwrócony przez KSeF pokazuje po polsku, z informacją, co poprawić. Działa obok Twojego programu księgowego, nie zamiast niego. Zobacz, jak działa FakturaFlow.
Podsumowanie
Kody 21402 i 21403 znaczą, że rozmiar albo skrót wysłanej faktury nie zgadza się z danymi, które program sam do niej dołączył. To błąd programu, nie treści faktury, więc nie poprawiaj danych na fakturze, tylko zgłoś wzorzec dostawcy. Pilną fakturę możesz w tym czasie wysłać inną drogą. Opisy innych kodów znajdziesz 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.