Jak interpretować kody błędów KSeF w Twojej firmie?

Bramka KSeF odpowiada numerem i jednym zdaniem, a Ty w tej samej minucie musisz zdecydować jedną z trzech rzeczy: poprawić plik XML, ponowić żądanie albo oddać sprawę księgowej. To trzy różne decyzje, trzy różne koszty i trzy różne terminy.

Zgodnie z obecną ustawą kary z art. 106ni ustawy o VAT obowiązują od 1 stycznia 2027 r. Ministerstwo Finansów zapowiedziało 16 września 2026 r. ich przesunięcie na 1 stycznia 2028 r. — to projekt ustawy, jeszcze nieuchwalony. Przesunięcie dotyczy tylko kar, a nie samego obowiązku korzystania z KSeF. Faktura, która nie weszła do systemu, przestaje być problemem technicznym i staje się ryzykiem finansowym, więc warto mieć w firmie jedną rzecz: procedurę czytania komunikatów bramki, a nie odruch przeklejania numeru do Google.

Ten tekst jest mapą. Pokazuje, z czego składa się odpowiedź KSeF, co oznacza każda rodzina kodów, jak wygląda gotowe rozgałęzienie decyzji i które kody wolno po prostu ponowić. Pełną listę kodów publikuje Ministerstwo Finansów w dokumentacji API; tutaj omawiamy te, które zdarzają się najczęściej.

Komunikat KSeF ma trzy warstwy, nie jedną

Numer błędu bez kontekstu jest bezużyteczny. Ten sam 21405 raz oznacza literówkę w parametrze zapytania, a raz źle zmapowane pole w ERP. Dlatego każdy komunikat czyta się na trzech poziomach:

1. Status HTTP — czy żądanie w ogóle zostało przyjęte przez bramkę.

2. exceptionCode i exceptionDescription — konkretna przyczyna po stronie KSeF.

3. Status faktury lub sesji — czy dokument już dostał numer KSeF, czy jeszcze nie istnieje w systemie.

Dopiero te trzy razem mówią, czyj to problem. Warstwa pierwsza i druga należą do integracji. Warstwa trzecia — do księgowości, bo to ona decyduje, czy potrzebna jest korekta.

Do tego dochodzą dwa identyfikatory, które warto logować zawsze: referenceNumber operacji i traceId odpowiedzi. Bez nich zgłoszenie do Ministerstwa Finansów albo do dostawcy oprogramowania jest opowieścią, a nie zgłoszeniem.

Mapa rodzin kodów: co mówi pierwszy człon numeru

Numeracja KSeF 2.0 nie jest przypadkowa. Pierwsze cyfry wskazują obszar systemu, który odrzucił żądanie — i to wystarcza, żeby w kilka sekund skierować sprawę do właściwej osoby.

Zasada praktyczna: wszystko poniżej 214xx to zwykle konfiguracja, a nie faktura. Poprawianie dokumentu przy błędzie uwierzytelnienia to najczęstszy sposób na stracenie godziny.

Statusy HTTP: pierwsze rozgałęzienie

Uwaga: liczby 410 i 415 pojawiają się także jako statusy przetwarzania faktury w sesji (a nie jako kod HTTP odpowiedzi) — przykład niżej dotyczy właśnie takiego statusu. Najdroższy błąd interpretacyjny w tej tabeli to 429. Przy limitach API łatwo wziąć go za odrzucenie dokumentu i zacząć „poprawiać" poprawną fakturę. Limity są opisane w dokumentacji CIRF/MF.

Najczęstsze kody i co z nimi zrobić

Podpis i dokument autoryzacyjny (9xxx)

Sesje, faktury i eksport (211xx)

Paczka wsadowa (212xx)

Uwierzytelnienie i autoryzacja (213xx)

Walidacja dokumentu i danych (214xx)

Certyfikaty i tokeny (250xx, 260xx)

Katalog KSeF 2.0 jest większy niż powyższa lista — źródłem prawdy pozostaje dokumentacja API na api.ksef.mf.gov.pl i przewodnik dla integratorów CIRF/MF.

Ten sam dokument, dwie różne odpowiedzi: przykład z naszego wdrożenia

10 września 2026 na środowisku testowym MF sprawdzaliśmy faktury z załącznikiem. Ta sama faktura, wysłana sesją interaktywną, wracała ze statusem przetwarzania 415 i komunikatem o braku możliwości wysłania faktury z załącznikiem. Ta sama faktura w sesji wsadowej — przyjęta. I ta sama sesja interaktywna przyjmowała ten dokument bez węzła załącznika.

Wniosek jest niewygodny, ale ważny: część komunikatów nie mówi „dokument jest zły", tylko „tego nie robi się tym kanałem". Gdyby ktoś zaczął od poprawiania XML-a, poprawiałby plik, który jest poprawny. Różnice między trybami opisuje dokumentacja sesji wsadowej.

Błąd to nie zawsze brak faktury w systemie

Najdroższe pomyłki dzieją się po drugiej stronie granicy: faktura już ma numer KSeF.

Przyjęcie dokumentu przez bramkę oznacza zgodność ze strukturą logiczną — i tyle. KSeF nie sprawdza poprawności rozliczenia VAT, zasadności transakcji ani arytmetyki. Faktura z błędną stawką przejdzie walidację techniczną bez jednego komunikatu.

Konsekwencja praktyczna: dokumentu, który dostał numer KSeF, nie da się „cofnąć" w systemie sprzedażowym. Zostaje faktura korygująca. Korekta techniczna dotyczy wyłącznie faktury wystawionej w trybie offline, którą KSeF odrzucił — dokumentu z numerem KSeF nią nie poprawisz. To już decyzja księgowa, nie integracyjna, i właśnie dlatego trzeciej warstwy komunikatu (statusu faktury) nie wolno pomijać.

Osobny przypadek to duplikaty. KSeF rozpoznaje je po kombinacji danych sprzedawcy, rodzaju faktury i numeru dokumentu, a unikalność utrzymuje przez lata — ponowna wysyłka „na wszelki wypadek" nie jest neutralna.

Checklista: co zapisać przy każdym błędzie

1. Status HTTP odpowiedzi.

2. exceptionCode i pełną treść exceptionDescription.

3. referenceNumber operacji (sesji, wniosku, eksportu).

4. traceId z odpowiedzi.

5. Środowisko: testowe czy produkcyjne.

6. Status faktury: czy nadano numer KSeF.

7. Znacznik czasu w UTC — przy limitach i sesjach rozstrzyga sekunda.

Te siedem pól zamienia dyskusję „u nas nie działa" w zgłoszenie, które da się rozpatrzyć. Pełne procedury zgłaszania opisuje strona wsparcia dla integratorów.

Podsumowanie

Kody błędów KSeF wyglądają na temat wyłącznie techniczny, ale rozstrzygają rzeczy księgowe: czy faktura istnieje, czy termin został zachowany, czy potrzebna jest korekta. Trzy warstwy odpowiedzi, mapa rodzin kodów i siedem pól z checklisty wystarczą, żeby przestać zgadywać.

W Biurko 28 najczęstszych kodów tłumaczymy na zdanie po polsku i jedną sugerowaną akcję, pozostałe pokazujemy tekstem Ministerstwa Finansów, a wysyłkę po błędach przejściowych ponawiamy automatycznie (do trzech prób, a po 429 czekamy czas wskazany przez bramkę). Wypróbuj Biurko — nowa firma dostaje 14 dni planu TEAM bez karty i zobacz, jak wygląda wysyłka do KSeF, w której nie trzeba czytać numerów.

FAQ

Co oznacza błąd 21401 w KSeF? Dokument nie jest zgodny ze schemą XSD. W praktyce najczęściej chodzi o strukturę FA(3), niewypełnione pole obowiązkowe albo kodowanie pliku inne niż UTF-8 bez BOM. Numer sam w sobie nie wskazuje pola — wskazuje je komunikat walidatora zwrócony razem z kodem.

Czy błąd 429 oznacza, że faktura została odrzucona? Nie. To przekroczenie limitu zapytań do API i dotyczy wyłącznie integracji. Faktura nie jest błędna. Rozwiązaniem jest odczytanie nagłówka Retry-After, kolejkowanie żądań i wykładniczy backoff, a nie zmiany w dokumencie.

Czy przyjęcie faktury przez KSeF oznacza, że jest poprawna? Nie. System weryfikuje zgodność ze strukturą logiczną i poprawność techniczną pliku. Nie sprawdza poprawności rozliczenia VAT ani arytmetyki. Faktura z błędem merytorycznym może otrzymać numer KSeF i wymagać później korekty.

Gdzie jest oficjalna lista kodów błędów KSeF? Źródłem prawdy jest kontrakt OpenAPI i dokumentacja API 2.0 na api.ksef.mf.gov.pl oraz repozytorium CIRF/MF z przewodnikiem dla integratorów i changelogiem, w którym Ministerstwo publikuje nowe kody.

Co zrobić, gdy faktura ma już numer KSeF, ale zawiera błąd? Nie da się jej usunąć ani nadpisać. Drogą jest faktura korygująca; korekta techniczna dotyczy wyłącznie faktury wystawionej w trybie offline, którą KSeF odrzucił.