Błąd 430 w KSeF: „Błąd weryfikacji pliku faktury”, czyli kłopot z samym plikiem XML

Krajowy System e-Faktur (KSeF) odrzucił fakturę ze statusem 430 i opisem „Błąd weryfikacji pliku faktury”. Faktura nie została przyjęta i nie dostała numeru KSeF. Rzadziej ten sam numer 430 dostaje cała sesja wsadowa, z opisem „Błąd dekompresji pierwotnego archiwum”.

Na tej stronie znajdziesz wymagania, które MF stawia każdemu plikowi faktury, przyczyny, które z nich wynikają, i kroki naprawy dla obu wariantów. Pozostałe kody opisujemy na stronie z pełną listą kodów błędów KSeF.

Co oznacza kod 430

Numer 430 występuje w KSeF w dwóch miejscach:

Kod 430 nie jest kodem HTTP ani statusem logowania. Nie ma go też wśród statusów sesji interaktywnej. Większość tej strony dotyczy statusu faktury, a wariant wsadowy opisujemy niżej.

Co KSeF sprawdza w pliku faktury

Dokumentacja MF podaje dla statusu 430 tylko opis, bez przyczyn. Opisuje natomiast, co KSeF sprawdza w każdej fakturze (dokument „Weryfikacja faktury” w oficjalnym repozytorium API KSeF 2.0). Pierwsza grupa wymagań to „Weryfikacja XML”. Faktura musi:

• być poprawnym dokumentem XML 1.0,
• mieć kodowanie UTF-8 bez znacznika BOM,
• być „zgodna z zadeklarowanym schematem podanym przy otwarciu sesji”,
• nie mieć w prologu XML deklaracji kodowania innego niż UTF-8,
• nie zawierać instrukcji przetwarzania,
• nie zawierać znaków Unicode z zakresów niezalecanych.

Dokumentacja dodaje: „Niespełnienie któregokolwiek z powyższych wymagań spowoduje odrzucenie faktury”. Osobno podaje limit rozmiaru: faktura bez załączników może mieć najwyżej 1 MB (1 000 000 bajtów), z załącznikami 3 MB (3 000 000 bajtów).

Ważne zastrzeżenie: dokumentacja nie łączy tych wymagań z kodem 430 wprost. Przypisanie ich do 430 to nasz wniosek z opisu „Błąd weryfikacji pliku faktury”.

430 czy 450

Kod 450 ma opis „Błąd weryfikacji semantyki dokumentu faktury”. Z zestawienia obu opisów wynika podział. Przy 430 problemem jest plik: czy to w ogóle poprawny XML, w dobrym kodowaniu, schemacie i rozmiarze. Przy 450 problemem jest treść: dane w technicznie poprawnym pliku łamią zasady FA(3).

Dokumentacja tej granicy nie opisuje. Niezgodność ze schematem może skończyć się jednym albo drugim kodem. W tekście o błędzie 450 w KSeF opisujemy przypadek starej przestrzeni nazw FA(2), który dał właśnie 450. Praktyczna reguła: przy 430 szukaj usterki w pliku, przy 450 w polach faktury.

Najczęstsze przyczyny

Dokumentacja nie podaje przyczyn kodu 430. Poniższe wynikają z wymagań opisanych wyżej. Kolejność to nasza ocena: od usterek najłatwiejszych do wprowadzenia w pracy biura.

1. Niewidoczne znaki wklejone do nazwy towaru

Nazwa pozycji albo opis skopiowany z Excela, PDF-a lub Worda potrafi zawierać znaki, których nie widać na ekranie. Chodzi o znaki sterujące, na przykład tabulator pionowy. Spośród znaków sterujących o kodach poniżej 32 standard XML 1.0 dopuszcza tylko tabulator, nową linię i powrót karetki. Z każdym innym plik nie jest poprawnym XML. Podobnie działają znaki z zakresów Unicode, które dokumentacja MF wyklucza jako niezalecane.

Jak rozpoznać: 430 dotyczy jednej faktury albo faktur jednego klienta, a inne przechodzą. W nazwie pozycji jest tekst skopiowany z innego dokumentu. Czasem w podglądzie widać pusty kwadrat, dziwny odstęp albo połamaną linię.

2. Znacznik BOM na początku pliku

BOM to trzy niewidoczne bajty (EF BB BF) na samym początku pliku. Niektóre edytory tekstu i funkcje eksportu dodają je przy zapisie w UTF-8. KSeF wymaga UTF-8 bez BOM.

Jak rozpoznać: 430 dostają pliki, które ktoś otworzył i zapisał w edytorze przed wysyłką. Albo wszystkie pliki z jednej ścieżki eksportu. Notepad++ pokazuje wtedy na pasku stanu kodowanie „UTF-8-BOM” zamiast „UTF-8”.

3. Inne kodowanie albo instrukcja przetwarzania na początku pliku

Jeśli prolog XML w pierwszej linii pliku brzmi <?xml version="1.0" encoding="windows-1250"?> albo deklaruje ISO-8859-2, plik łamie wymaganie MF.

Drugi wariant: prolog deklaruje UTF-8, ale polskie litery zapisano w innym kodowaniu. W edytorze ustawionym na UTF-8 „ą” czy „ł” wyglądają wtedy jak przypadkowe znaki. Taki plik nie jest poprawnym UTF-8.

Trzeci wariant to instrukcja przetwarzania, czyli wpis <? … ?> poza samym prologiem, na przykład <?xml-stylesheet …?> do wyświetlania faktury w przeglądarce. MF takich wpisów nie dopuszcza.

Jak rozpoznać: obejrzyj w edytorze dwie pierwsze linie pliku. Ten błąd dotyczy zwykle wszystkich faktur z danego programu albo eksportu.

4. Plik nie pasuje do schematu zadeklarowanego przy otwarciu sesji

Otwierając sesję, program deklaruje, w jakiej strukturze wyśle faktury. Jeśli zadeklarował FA(3), każda faktura musi być dokumentem FA(3). Plik w starszej strukturze FA(2) albo z inną przestrzenią nazw nie pasuje do deklaracji. Przestrzeń nazw FA(3) to http://crd.gov.pl/wzor/2025/06/25/13775/.

Do tej samej grupy należy zgodność z samym schematem XSD: obowiązkowe elementy, ich kolejność i format wartości, na przykład daty w formacie RRRR-MM-DD. Dokumentacja nie mówi, czy takie błędy dają 430, czy 450. Stara przestrzeń nazw FA(2) dała nam 450.

Jak rozpoznać: odrzucane są wszystkie faktury z jednego programu, często od razu po aktualizacji albo zmianie konfiguracji. Adres przestrzeni nazw w pliku jest inny niż podany wyżej. Pola i strukturę FA(3) opisujemy w tekście o schemacie FA(3).

5. Plik większy niż 1 MB

Limit dla faktury bez załączników to 1 000 000 bajtów. Taki rozmiar osiągają faktury z bardzo dużą liczbą pozycji. Plik powiększają też wcięcia i długie opisy powtarzane w każdym wierszu.

Jak rozpoznać: we właściwościach pliku Windows pokazuje dokładną liczbę bajtów. Porównaj ją z 1 000 000.

Limit 3 MB dotyczy tylko faktur z załącznikami. Te wysyła się co do zasady w sesji wsadowej, po wcześniejszym zgłoszeniu w usłudze e-Urząd Skarbowy (błąd 415 w KSeF).

Co zrobić krok po kroku

1. Sprawdź, czego dotyczy 430. Opis „Błąd dekompresji pierwotnego archiwum” przy sesji wsadowej oznacza problem z paczką. Wtedy przejdź do części o sesji wsadowej niżej.
2. Przeczytaj szczegóły błędu. Odpowiedź KSeF ze statusem faktury ma pole na szczegóły. Jeśli program je pokazuje, zacznij od nich.
3. Policz, ile faktur dostało 430. Jedna faktura albo jeden klient: sprawdź przyczyny 1 i 5. Wszystkie faktury z programu: sprawdź przyczyny 2, 3 i 4.
4. Obejrzyj plik XML. Jeśli program pozwala, zapisz plik odrzuconej faktury i otwórz go w Notepad++. Sprawdź kodowanie, dwie pierwsze linie, przestrzeń nazw i rozmiar.
5. Popraw dane w programie, nie w pliku. Usuń z nazw pozycji tekst wklejony z innych dokumentów i wpisz go ręcznie. Ręczna edycja XML-a łatwo wprowadza nowy błąd, na przykład BOM.
6. Wyślij fakturę ponownie. Odrzucona faktura nie trafiła do KSeF, więc poprawioną wysyłasz pod tym samym numerem. Najpierw upewnij się, że ta faktura nie ma już numeru KSeF z innej, wcześniejszej wysyłki. Inaczej skończy się to kodem 440 „Duplikat faktury”.
7. Gdy 430 dotyczy wszystkich faktur, zgłoś to dostawcy programu. Dołącz plik XML, godzinę i numer referencyjny sesji. Plik buduje program, więc trwale naprawi to tylko dostawca.
8. Kiedy pisać do MF. Jeśli dostawca potwierdzi, że plik spełnia wszystkie wymagania z dokumentacji, a 430 wraca, zgłoś sprawę przez formularz MF albo na adres jpk.helpdesk@mf.gov.pl. Podaj numer referencyjny sesji, godzinę i środowisko.

Kod 430 w sesji wsadowej

W sesji wsadowej program nie wysyła faktur pojedynczo. Pakuje je w jedno archiwum ZIP i dzieli je na części. Każdą część szyfruje kluczem AES wygenerowanym dla tej sesji i przesyła. KSeF robi to samo w odwrotnej kolejności: odszyfrowuje klucz, potem części, składa archiwum i je rozpakowuje.

Na te etapy dokumentacja ma osobne statusy sesji wsadowej:

• 415 „Błąd odszyfrowania dostarczonego klucza”,
• 435 „Błąd odszyfrowania zaszyfrowanych części archiwum”,
• 430 „Błąd dekompresji pierwotnego archiwum”.

„Pierwotne archiwum” to paczka ZIP sprzed podziału i szyfrowania. Przyczyn dokumentacja nie podaje. Z kolejności etapów wynika nasz wniosek: przy 430 odszyfrowanie się udało, ale wynik nie jest archiwum, które da się rozpakować. Błąd samego odszyfrowania ma własny kod, opisany w tekście o błędzie 435 w KSeF.

Możliwe przyczyny, wszystkie po stronie programu:

• program zaszyfrował archiwum, zanim skończył je zapisywać (ZIP trzyma spis zawartości na końcu pliku, więc niedokończonego archiwum nie da się rozpakować),
• plik ma inny format niż ZIP, choć tak go nazwano,
• archiwum uszkodziło się przy budowie, na przykład gdy programowi zabrakło pamięci albo miejsca na dysku.

Co zrobić: nie poprawiaj faktur, bo problem dotyczy opakowania. Przed ponowną wysyłką sprawdź, czy żadna faktura z paczki nie ma numeru KSeF. Z archiwum, którego nie da się rozpakować, KSeF faktur nie odczyta, ale dokumentacja tego nie opisuje. Zgłoś błąd dostawcy z numerem referencyjnym sesji. Po poprawce program zbuduje paczkę od nowa i wyśle ją w nowej sesji.

Jak temu zapobiec

• Nie wklejaj nazw pozycji z PDF-ów i arkuszy bez sprawdzenia. Krótką nazwę szybciej przepisać, niż szukać w niej niewidocznego znaku.
• Nie zapisuj plików XML w przypadkowych edytorach. Jeśli musisz, wybierz „UTF-8”, nie „UTF-8 z BOM”.
• Po aktualizacji programu wyślij najpierw jedną fakturę. Gdy dostanie status 200 „Sukces”, wysyłaj resztę.

Dla programisty

Waliduj każdy plik oficjalnym schematem XSD FA(3) opublikowanym przez MF, na bajtach, które naprawdę wyślesz. XSD nie wychwyci wszystkiego, więc sprawdź osobno: brak bajtów EF BB BF na początku, prolog pominięty albo z UTF-8, brak instrukcji przetwarzania, a z kodów poniżej 0x20 tylko 0x09, 0x0A i 0x0D. Rozmiar licz w bajtach po zakodowaniu do UTF-8 i porównuj z 1 000 000 (3 000 000 z załącznikami). Przestrzeń nazw elementu głównego musi odpowiadać schematowi z otwarcia sesji. Plik zgodny z XSD nadal może dostać 450. W sesji wsadowej rozpakuj gotowe archiwum ZIP testowo standardową biblioteką, zanim podzielisz je na części i zaszyfrujesz.

Chcesz łapać takie błędy przed wysyłką? FakturaFlow sprawdza każdą fakturę według reguł FA(3), zanim trafi do KSeF: długości pól, niedozwolone znaki, datę wystawienia z przyszłości, format NIP i numeru VAT UE. Błędy zwrócone przez KSeF pokazuje po polsku, z informacją, co poprawić. Działa obok Twojego programu księgowego, nie zamiast niego. Załóż konto w FakturaFlow.

Podsumowanie

Status faktury 430 „Błąd weryfikacji pliku faktury” według opisu dotyczy samego pliku XML, a nie pól faktury. Sprawdź znaki wklejone do nazw pozycji, BOM, kodowanie i pierwszą linię pliku, przestrzeń nazw oraz rozmiar. Gdy 430 dostała sesja wsadowa z opisem „Błąd dekompresji pierwotnego archiwum”, najpewniej winna jest paczka zbudowana przez program. 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.