Kody błędów KSeF: co system faktycznie odrzuca i jak to naprawić

Odrzucona faktura nie istnieje. Z prawnego punktu widzenia nigdy nie powstała. Nie możesz jej skorygować, anulować ani zreferować w JPK_V7. Naprawiasz błąd i wysyłasz ponownie. To rozróżnienie brzmi banalnie, dopóki nie patrzysz na kod wyjątku 21401 o 16:55 w piątek, a klient czeka na płatność.

Badanie Grant Thornton z kwietnia 2026 wykazało, że 74% firm napotkało błędy e-fakturowania w pierwszym miesiącu obowiązkowego KSeF. Dwadzieścia procent zadeklarowało, że te błędy zakłóciły codzienne operacje. Problem nie jest teoretyczny. To najczęstsze doświadczenie po starcie w polskim ekosystemie fakturowania.

Ten artykuł mapuje każdy kod odrzucenia w taksonomii KSeF 2.0 do jego przyczyny, błędnego pola i dokładnej naprawy. Nazywa też zmyślone kody krążące w artykułach z farm treści, ponieważ działanie na fałszywej taksonomii odrzuceń marnuje czas i opóźnia ponowne wysłanie.

KSeF odrzuca tylko z dwóch powodów

Ministerstwo Finansów potwierdziło publicznie w maju 2026, że KSeF waliduje tylko dwie rzeczy: zgodność ze schematem FA(3) i uprawnienia nadawcy. System nie sprawdza arytmetyki VAT. Nie weryfikuje danych nabywcy względem rejestru podatkowego. Nie waliduje wartości kursu waluty. Nie odsyła kwot faktury do żadnej zewnętrznej bazy danych.

Faktura zgodna ze schematem, ale z błędną stawką VAT, błędnym NIP nabywcy i wymyślonym kursem walut przejdzie walidację KSeF i otrzyma numer KSeF. Państwo przypisuje numer, wystawia UPO (potwierdzenie przyjęcia), a faktura wchodzi do obiegu prawnego. Błąd merytoryczny ujawnia się tygodnie później podczas uzgadniania, podczas kontroli, albo gdy nabywca odkrywa, że nie może odliczyć VAT naliczony, bo faktura nosi NIP kogoś innego.

To nie jest wada projektu. To architektura. KSeF to system rozliczeniowy (clearance), nie system walidacyjny. Walidacja merytoryczna to obowiązek podatnika, co oznacza, że jest albo ręczną listą kontrolną, albo funkcją produktu. Plandesk dostarcza walidację przed wysłaniem, która sprawdza to, czego KSeF nie sprawdza: sumę kontrolną NIP i weryfikację w rejestrze, arytmetykę VAT, duplikaty numerów faktur, weryfikację kursu NBP i spójność kodów GTU.

Statusy sesji: kiedy faktura faktycznie istnieje

Zanim rozkodujesz kody odrzuceń, musisz rozumieć statusy sesji. Najbardziej kosztowny błąd po starcie to nie odrzucenie. To duplikat spowodowany ponownym wysłaniem podczas przetwarzania.

Statusy 100 i 150 nie są błędami. Oznaczają, że KSeF przyjął fakturę i ją przetwarza. Czas przetwarzania przez Ministerstwo waha się od sekund do godzin pod obciążeniem. Ponowne wysłanie w tym oknie tworzy duplikat faktury z innym numerem KSeF, co jest najczęstszą przyczyną odrzuceń z kodem 440.

Jeśli używasz narzędzia z automatycznym odpytywaniem, pozwól mu działać. Jeśli używasz Aplikacji Podatnika ręcznie, odśwież stronę statusu sesji. Nie klikaj „wyślij" ponownie.

Prawdziwa taksonomia kodów błędów

KSeF 2.0 zwraca status HTTP plus exceptionCode w treści odpowiedzi. Poniższe kody pochodzą z oficjalnej dokumentacji OpenAPI utrzymywanej przez Ministerstwo Finansów. To kody, które praktycy faktycznie napotykają.

Kod 21401: błąd walidacji schematu FA(3)

Co oznacza: XML, który wysłałeś, nie jest zgodny ze schematem FA(3).

Typowe przyczyny:

• Używany przestarzały szablon FA(2) (FA(2) został trwale wyłączony 1 lutego 2026)
• Bajty BOM (byte order mark) na początku pliku XML
• Zła kolejność elementów lub brak elementów obowiązkowych
• Nieprawidłowa deklaracja przestrzeni nazw

Naprawa: Wygeneruj fakturę ponownie z aktualnego szablonu FA(3). Jeśli używasz oprogramowania fakturowego, zaktualizuj je do najnowszej wersji. Nigdy nie edytuj XML ręcznie. Schemat jest na tyle rygorystyczny, że ręczne edycje wprowadzają więcej błędów, niż naprawiają.

Scenariusz: Faktura freelancera zostaje odrzucona z kodem 21401, ponieważ jego narzędzie fakturowe było ostatnio aktualizowane w styczniu 2026 i nadal generuje XML FA(2). Naprawą jest aktualizacja oprogramowania, nie edycja XML.

Kod 21405: błąd walidacji danych wejściowych

Co oznacza: Walidacja formatu na poziomie pola nie powiodła się. XML jest strukturalnie poprawny, ale konkretne pole zawiera dane w złym formacie.

Typowe przyczyny:

• NIP z myślnikami, spacjami lub prefiksem „PL" (FA(3) wymaga 10 cyfr, bez separatorów)
• Data w złym formacie (FA(3) wymaga YYYY-MM-DD)
• Pole numeryczne z przecinkiem jako separatorem dziesiętnym zamiast kropki
• KursWaluty z mniejszą liczbą niż 6 miejsc po przecinku

Naprawa: Popraw dane źródłowe w karcie kontrahenta lub formularzu faktury, następnie wyślij ponownie. Odpowiedź błędu zawiera ścieżkę pola, która wskazuje dokładnie, który element naprawić.

Scenariusz: Faktura jednoosobowej działalności zostaje odrzucona z kodem 21405, ponieważ karta kontrahenta przechowuje NIP nabywcy jako „PL-123-456-78-90". FA(3) wymaga „1234567890". Napraw kartę kontrahenta, wygeneruj ponownie, wyślij.

Kod 21301: błąd autoryzacji

Co oznacza: Nadawca nie ma uprawnień do wystawiania faktur dla NIP w nagłówku faktury.

Typowe przyczyny:

• Token wygasł (tokeny KSeF mają okres ważności zależny od typu uprawnienia)
• Token wystawiony dla innego NIP niż ten w fakturze
• Administrator nadał uprawnienia wystawiania, ale uprawnienie nie zostało jeszcze propagowane
• Używanie logowania osobistego (Profil Zaufany) zamiast tokena lub certyfikatu

Naprawa: Wygeneruj token ponownie z odpowiednimi zakresami dla NIP wystawiającego. Jeśli używasz logowania osobistego, przełącz na autoryzację opartą na tokenie. Autoryzacja tokenem była zalecaną metodą przed startem i stała się de facto standardem po załamaniu Profilu Zaufanego 2-3 lutego 2026.

Scenariusz: Biuro rachunkowe próbuje wystawić fakturę dla nowego klienta, ale otrzymuje 21301. Token biura został wystawiony, zanim klient został dodany do uprawnień KSeF. Naprawa to nadanie uprawnień wystawiania dla NIP klienta, następnie regeneracja tokena.

Kod 440: duplikat faktury

Co oznacza: Faktura z tym samym numerem od tego samego wystawcy już istnieje w KSeF.

Typowe przyczyny:

• Ślepe ponowne wysłanie po timeout (najczęstsza przyczyna)
• Równoległe wystawianie przez aplikację fakturową i Aplikację Podatnika
• Status sesji nie sprawdzony przed ponownym wysłaniem

Naprawa: Odpytaj KSeF po własnym numerze faktury przed ponownym wysłaniem. Jeśli pierwsze wysłanie powiodło się (status 200), zaakceptuj istniejącą fakturę. Nie twórz duplikatu. Jeśli pierwsze wysłanie faktycznie nie powiodło się, napraw błąd i wyślij ponownie z tym samym numerem faktury.

Scenariusz: Użytkownik wysyła fakturę, otrzymuje timeout i wysyła ponownie. Pierwsze wysłanie faktycznie powiodło się, ale odpowiedź była opóźniona. Drugie wysłanie trafia na 440. Prawidłowe działanie to sprawdzenie statusu pierwszej sesji, znalezienie 200 i użycie tego numeru KSeF.

HTTP 500, 503, 429: błędy po stronie serwera

Co oznacza: Platforma KSeF jest przeciążona lub ogranicza częstotliwość zapytań.

Typowe przyczyny:

• Fale ruchu w okresie startu (luty i kwiecień 2026)
• Rate limiting po zbyt wielu zapytaniach w krótkim oknie
• Przejściowe problemy infrastruktury

Naprawa: Wdróż retry z wycofaniem (backoff). Jeśli błąd utrzymuje się, przełącz na tryb offline24 (wystaw fakturę lokalnie, wyślij do następnego dnia roboczego). Data wystawienia P_1 jest zachowana w trybie offline, więc data prawna faktury nie przesuwa się.

Faktury-widma: zaakceptowane, ale niewidoczne

Wzorzec, który nie generuje kodu odrzucenia, ale powoduje równie duży ból: faktura jest zaakceptowana (status 200, numer KSeF przypisany, UPO wystawione), ale nabywca nie widzi jej w swojej skrzynce KSeF. Ich odliczenie VAT jest zablokowane. Eksperci przypisują to błędom integracji ERP z KSeF i niejasnej semantyce statusów wysłano/przyjęto/odrzucono.

Faktura istnieje. Jest w obiegu prawnym. Księgowy nabywcy po prostu nie ma do niej dostępu. Obejście polega na tym, że sprzedawca udostępnia numer KSeF i UPO bezpośrednio nabywcy, który może następnie odpytać KSeF ręcznie. Strukturalna naprawa to lepsza synchronizacja statusów między KSeF a komercyjnymi systemami księgowymi, co jest jednym z problemów, które pakiet „7 ulepszeń" Ministerstwa na 1 stycznia 2027 ma adresować.

Zmyślone kody błędów do zignorowania

Farmy treści wymyśliły kody błędów, które nie istnieją w dokumentacji API KSeF. Jeśli wyszukasz kody błędów KSeF, znajdziesz artykuły referencujące kody jak „TOTAL_MISMATCH", „NIP_REGISTRY_REJECTION" czy „VAT_RATE_INVALID". Te kody są zmyślone. Nie odpowiadają żadnemu exceptionCode w oficjalnej specyfikacji OpenAPI.

Ministerstwo Finansów oświadczyło publicznie, że KSeF nie waliduje arytmetyki, danych nabywcy ani stawek VAT. Każdy artykuł twierdzący, że KSeF odrzuca faktury za błędne kwoty VAT lub niezarejestrowane NIP nabywcy jest w błędzie. Te błędy przechodzą przez KSeF. Ujawniają się później jako korekty, kontrole lub utracone odliczenia VAT naliczony.

Jeśli napotkasz kod błędu niewymieniony w oficjalnej dokumentacji, sprawdź źródło. Autorytatywną referencją jest specyfikacja OpenAPI publikowana przez Ministerstwo Finansów i mirrorowana w repozytorium dokumentacji API KSeF.

Siedem sprawdzeń przed każdym wysłaniem

Wykonaj te sprawdzenia przed wysłaniem jakiejkolwiek faktury do KSeF. Wyłapują błędy, których KSeF nie wyłapie.

1. Format NIP: 10 cyfr, bez myślników, bez spacji, bez prefiksu „PL".
2. Suma kontrolna NIP: Zweryfikuj cyfrę kontrolną. KSeF tego nie sprawdza.
3. Weryfikacja w rejestrze: Sprawdź, czy nabywca istnieje na białej liście podatników VAT.
4. Arytmetyka VAT: Netto razy stawka równa się VAT. Netto plus VAT równa się brutto. Sprawdź każdą pozycję.
5. Unikalność numeru faktury: Odpytaj KSeF po własnym numerze faktury przed wysłaniem.
6. Spójność dat: Data wystawienia (P_1) to dzisiaj lub w oknie offline24. Bez cofania dat.
7. Pola walutowe: KodWaluty to prawidłowy kod ISO 4217. KursWaluty ma 6 miejsc po przecinku. Kurs odpowiada tabeli NBP dla właściwego dnia.

Te sprawdzenia zajmują sekundy w oprogramowaniu i eliminują większość błędów po starcie. Wykonywanie ich ręcznie jest możliwe, ale podatne na błędy, dlatego walidacja przed wysłaniem istnieje jako funkcja produktu, nie jako ćwiczenie dokumentacyjne.

Niniejszy materiał ma charakter informacji ogólnej i nie stanowi porady prawnej ani podatkowej. W konkretnej sytuacji zweryfikuj aktualne przepisy lub skonsultuj się z doradcą.