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.
Okres bez sankcji kończy się 31 grudnia 2026 r. Od 1 stycznia 2027 r. faktura, która nie weszła do systemu, przestaje być problemem technicznym i staje się ryzykiem finansowym. Do tego czasu 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łny katalog — 133 komunikaty z tłumaczeniem i reakcją — znajdziesz w Słowniku błędów KSeF.
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:
Status HTTP — czy żądanie w ogóle zostało przyjęte przez bramkę.
exceptionCodeiexceptionDescription— konkretna przyczyna po stronie KSeF.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.
Rodzina Obszar Kto to naprawia 9xxx podpis i dokument autoryzacyjny integrator 211xx uwierzytelnianie, sesje, pobieranie faktur, eksport integrator 212xx paczka wsadowa i jej części integrator 213xx autoryzacja i tokeny dostępowe administrator w firmie 214xx walidacja dokumentu i danych wejściowych integrator lub osoba wystawiająca fakturę 250xx certyfikaty KSeF administrator w firmie 260xx tokeny KSeF administrator w firmie
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
Status Znaczenie Reakcja 400 nieprawidłowe żądanie lub błąd walidacji danych wejściowych przeczytaj exceptionCode i listę errors w odpowiedzi 401 brak poprawnego uwierzytelnienia token, certyfikat, ważność sesji 403 brak uprawnień albo niedozwolony kontekst kontekst NIP i zakres uprawnień operacji 410 operacja wygasła i nie jest już dostępna rozpocznij proces od nowa 415 typ operacji niedozwolony dla tego trybu wysyłki zmień tryb (przykład niżej) 429 przekroczony limit żądań API Retry-After, kolejkowanie, backoff — nie ruszaj faktury 5xx błąd po stronie infrastruktury KSeF zapisz traceId, ponów zgodnie z procedurą retry
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)
Kod Komunikat Reakcja 9101 Nieprawidłowy dokument sprawdź dokument użyty w procesie podpisu 9102 Brak podpisu podpis nie został dołączony do żądania 9103 Przekroczona liczba dozwolonych podpisów zweryfikuj liczbę podpisów dla tego typu dokumentu
Sesje, faktury i eksport (211xx)
Kod Komunikat Reakcja 21111 Nieprawidłowe wyzwanie autoryzacyjne challenge, szyfrowanie i czas w procesie uwierzytelnienia 21115 Nieprawidłowy certyfikat ważność i zgodność certyfikatu z wymaganiami KSeF 21117 Nieprawidłowy identyfikator podmiotu dla typu kontekstu NIP nie pasuje do wybranego typu kontekstu 21155 Przekroczono dozwoloną liczbę faktur w sesji zamknij sesję i otwórz nową 21157 Nieprawidłowy rozmiar części pakietu deklaracja części ≠ rzeczywisty plik 21161 Przekroczono dozwoloną liczbę części pakietu przebuduj paczkę wsadową 21164 Faktura o podanym identyfikatorze nie istnieje numer KSeF, kontekst podmiotu, uprawnienia do pobrania 21165 Faktura nie jest jeszcze dostępna to nie jest błąd — odczekaj i ponów pobranie 21166 Korekta techniczna niedostępna prawdopodobnie została już przetworzona 21167 Status faktury nie pozwala na korektę techniczną sprawa dla księgowości, nie dla integratora 21173 Brak sesji o wskazanym numerze referencyjnym numer referencyjny lub środowisko (test/prod) 21175 Wynik zapytania nie istnieje referencja eksportu albo upłynął czas dostępności wyniku 21178 Nie znaleziono UPO dla podanych kryteriów UPO powstaje po zamknięciu sesji — ponów później 21180 Status sesji nie pozwala na operację sesja zamknięta lub anulowana 21181 Nieprawidłowe żądanie eksportu faktur kryteria i kontekst eksportu 21182 Osiągnięto limit trwających eksportów ogranicz równoległe eksporty 21183 Zakres filtrowania poza dostępnym zakresem danych zakres dat i typ daty
Paczka wsadowa (212xx)
Kod Komunikat Reakcja 21205 Pakiet nie może być pusty nie wszystkie zadeklarowane części zostały wysłane 21208 Przekroczono czas oczekiwania na upload lub finish sesja mogła zostać anulowana — powtórz proces 21217 Nieprawidłowe kodowanie znaków UTF-8, bez znacznika BOM
Uwierzytelnienie i autoryzacja (213xx)
Kod Komunikat Reakcja 21301 Brak autoryzacji token unieważniony lub operacja uwierzytelnienia nieukończona 21304 Brak uwierzytelnienia operacja o tym numerze referencyjnym nie istnieje w tym środowisku 21308 Próba wykorzystania metod autoryzacyjnych osoby zmarłej wymaga zmiany sposobu uwierzytelnienia podmiotu
Walidacja dokumentu i danych (214xx)
Kod Komunikat Reakcja 21401 Dokument niezgodny ze schemą XSD najczęstszy błąd „faktury”: struktura FA(3), pola obowiązkowe, kodowanie 21402 Nieprawidłowy rozmiar pliku deklarowany rozmiar ≠ rzeczywista długość treści 21403 Nieprawidłowy skrót pliku sposób liczenia hasha 21405 Błąd walidacji danych wejściowych czytaj szczegóły, nie numer — ten kod sam z siebie nic nie mówi 21406 Konflikt podpisu i typu uwierzytelnienia metoda uwierzytelnienia vs. typ certyfikatu 21418 Nieprawidłowy format tokena kontynuacji nie modyfikuj ręcznie tokena stronicowania 21470 Nieznany lub wycofany identyfikator klucza pobierz aktualny klucz publiczny dla swojego środowiska
Certyfikaty i tokeny (250xx, 260xx)
Kod Komunikat Reakcja 25001 Brak możliwości pobrania danych do CSR dla tej metody uwierzytelnienia zmień metodę uwierzytelnienia 25002 Brak możliwości złożenia wniosku certyfikacyjnego dla tej metody jw. 25003 Dane w CSR niezgodne z wektorem uwierzytelniającym dane podmiotu w CSR 25004 Niepoprawny format lub podpis CSR format i algorytm podpisu wniosku 25005 Wniosek certyfikacyjny nie istnieje numer referencyjny i środowisko 25006 Limit składanych wniosków certyfikacyjnych uporządkuj wnioski 25007 Limit posiadanych certyfikatów unieważnij nieużywane 25010 Nieprawidłowy typ lub długość klucza wymagania z dokumentacji certyfikatów 25011 Nieprawidłowy algorytm podpisu CSR algorytm i funkcja skrótu 26001 Nie można nadać tokenowi uprawnień, których podmiot nie posiada najpierw uprawnienia podmiotu 26002 Nie można wygenerować tokena dla obecnego typu kontekstu token tylko w dopuszczonym kontekście
Katalog KSeF 2.0 jest większy niż powyższa lista — pełne 133 pozycje wraz z kontraktem OpenAPI trzymamy w Słowniku błędów KSeF, a ź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 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 albo — w wąskim zakresie przewidzianym przepisami — korekta techniczna. 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
Status HTTP odpowiedzi.
exceptionCodei pełną treśćexceptionDescription.referenceNumberoperacji (sesji, wniosku, eksportu).traceIdz odpowiedzi.Środowisko: testowe czy produkcyjne.
Status faktury: czy nadano numer KSeF.
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 komunikaty bramki tłumaczymy na zdanie po polsku i na jedną sugerowaną akcję, a ponawianie żądań po 429 i 5xx dzieje się bez Twojego udziału. Wypróbuj Biurko przez 14 dni za darmo na biurko.io 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ć. Standardową drogą jest faktura korygująca; korekta techniczna jest dostępna wyłącznie w przypadkach przewidzianych przepisami i tylko dla określonych statusów dokumentu.