Kody błędów w KSeF 2.0 – co oznaczają i jak bezpiecznie na nie reagować?

Kody błędów w KSeF bardzo łatwo uznać za temat wyłącznie techniczny i przekazać go do zespołu IT albo dostawcy systemu ERP. W praktyce jednak komunikaty zwracane przez Krajowy System e-Faktur mają znacznie szersze znaczenie. Mogą wpływać na terminowość wystawienia faktury, prawidłowość rozliczeń podatkowych, proces księgowy, obieg dokumentów oraz odpowiedzialność organizacyjną pomiędzy finansami, księgowością i IT.

Piotr Steczyszyn

kody błędów ksef

Z perspektywy CFO, głównej księgowej czy osoby odpowiedzialnej za procesy finansowe nie warto patrzeć na kody błędów KSeF wyłącznie jak na listę numerów do przekazania integratorowi. Sama tabela błędów może być pomocna, ale nie rozwiązuje problemu. Przy KSeF 2.0 dużo ważniejsze jest ustalenie, na jakim etapie procesu pojawia się błąd, czy faktura została już skutecznie przyjęta do systemu, czy otrzymała numer KSeF oraz czy problem ma charakter techniczny, konfiguracyjny, księgowy czy podatkowy.


W praktyce dokładnie ten sam kod błędu może oznaczać zupełnie inne działania po stronie organizacji. Czasem wystarczy ponowić komunikację z systemem. Innym razem konieczna będzie poprawa mapowania danych w ERP, analiza podatkowa albo wystawienie faktury korygującej.


Czym są kody błędów KSeF?


Kody błędów KSeF to komunikaty zwracane przez system podczas wysyłki, odbioru lub przetwarzania faktur ustrukturyzowanych. Mogą dotyczyć:


  • uwierzytelnienia i autoryzacji,
  • certyfikatów oraz tokenów,
  • uprawnień do działania w określonym kontekście,
  • walidacji pliku XML,
  • statusu sesji interaktywnej lub wsadowej,
  • limitów API,
  • pobierania dokumentów i UPO,
  • błędów infrastruktury technicznej.

W praktyce oznacza to, że nie każdy błąd KSeF oznacza błąd faktury. Część komunikatów odnosi się wyłącznie do warstwy integracyjnej i nie wymaga poprawiania dokumentu.

Kody błędów KSeF a kody QR – to nie to samo


W praktyce pod hasłem „kody KSeF” pojawiają się dwa zupełnie różne tematy.


Pierwszy to kody błędów KSeF, czyli komunikaty systemowe zwracane przez API KSeF albo walidator dokumentu. Informują one m.in. o problemach z uwierzytelnieniem, tokenem, statusem sesji, limitem zapytań, strukturą XML albo pobieraniem faktury.


Drugi obszar to kody QR KSeF, nanoszone na wizualizację faktury w przypadkach przewidzianych przepisami i dokumentacją techniczną – zarówno przy użyciu faktury poza KSeF po jej przesłaniu do systemu, jak i w trybach offline/offline24 oraz w trybie awaryjnym. Ich rolą jest umożliwienie weryfikacji danych dokumentu i dostępu do faktury w KSeF.


To rozróżnienie ma znaczenie praktyczne. Kod QR nie jest błędem KSeF i nie oznacza problemu z dokumentem.

Księgowa z Optima

Czy każdy błąd KSeF oznacza błąd faktury?


Jednym z najczęstszych nieporozumień jest założenie, że skoro system zwrócił błąd, to automatycznie problem dotyczy treści faktury. Tak jednak nie musi być. Błąd może wynikać z:


  • nieprawidłowego żądania technicznego,
  • błędu uwierzytelnienia,
  • niewłaściwego kontekstu działania,
  • braku uprawnień,
  • wygasłego tokena,
  • przekroczenia limitów API,
  • błędnego statusu sesji,
  • konfiguracji integracji,
  • albo dopiero z samego pliku XML faktury.

Dlatego przy analizie błędów KSeF warto patrzeć na kilka poziomów odpowiedzi:


  1. Status HTTP – pierwszy sygnał techniczny, czy system przyjął żądanie.
  2. ExceptionCode (kod błędu KSeF) – szczegółowa przyczyna problemu.
  3. Status procesu faktury – czy dokument został skutecznie przyjęty do systemu i otrzymał numer KSeF.

Dopiero po takim rozróżnieniu można zdecydować, czy sprawa powinna trafić do IT, księgowości, podatków albo dostawcy systemu.


Status HTTP w KSeF – pierwszy sygnał problemu


Pierwszym poziomem komunikacji z KSeF jest status HTTP. Pokazuje on, czy żądanie zostało poprawnie obsłużone, czy wystąpił problem z autoryzacją, limitem zapytań albo działaniem infrastruktury.


400 – nieprawidłowe żądanie


Najczęściej oznacza problem z walidacją danych wejściowych, niepoprawnym żądaniem lub strukturą danych.


Co sprawdzić?


  • parametry endpointu,
  • treść odpowiedzi API,
  • ExceptionCode,
  • poprawność danych wejściowych,
  • plik XML faktury.

401 – brak poprawnego uwierzytelnienia


Najczęściej oznacza problem z tokenem, certyfikatem albo sesją uwierzytelniającą.


Co sprawdzić?


  • ważność tokena,
  • konfigurację podpisu,
  • certyfikat,
  • aktywność sesji.

403 – brak uprawnień


Użytkownik albo system nie ma odpowiednich praw do wykonania operacji.


Co sprawdzić?


  • kontekst NIP,
  • nadane uprawnienia,
  • typ uprawnień dla konkretnej operacji.

410 – operacja wygasła


Najczęściej oznacza, że czas dostępności danego procesu albo wyniku już upłynął.


429 – przekroczony limit zapytań API


To jeden z najczęściej źle interpretowanych błędów. Nie oznacza błędu faktury.


Oznacza wyłącznie zbyt dużą liczbę zapytań wykonywanych w określonym czasie. W takim przypadku rozwiązaniem nie jest poprawianie faktury, lecz:


  • kolejkowanie zapytań,
  • wdrożenie retry logic,
  • analiza nagłówka Retry-After,
  • optymalizacja integracji.

500 / 5xx – błąd po stronie KSeF


Najczęściej oznacza problem techniczny po stronie infrastruktury.


Co robić?


  • zabezpieczyć logi,
  • zapisać traceId,
  • ponowić operację zgodnie z procedurą retry,
  • monitorować komunikaty techniczne MF.

Czy przyjęcie faktury przez KSeF oznacza, że dokument jest poprawny?


Nie. To jedna z ważniejszych kwestii praktycznych. Pozytywne przyjęcie faktury przez KSeF i nadanie numeru KSeF nie oznacza automatycznie poprawności merytorycznej dokumentu.


System sprawdza głównie:


  • zgodność XML ze strukturą logiczną,
  • poprawność techniczną pliku,
  • zgodność ze schemą.

KSeF nie weryfikuje m.in.:


  • poprawności rozliczenia VAT,
  • zasadności transakcji,
  • poprawności rachunkowej,
  • zgodności biznesowej dokumentu.

W praktyce oznacza to, że faktura może przejść walidację techniczną, mimo że zawiera błąd rachunkowy lub podatkowy.


Jeżeli dokument został już przyjęty do systemu i nadano numer KSeF, nie można go po prostu usunąć lub poprawić w ERP. W takim przypadku trzeba przeanalizować, czy konieczne jest wystawienie faktury korygującej, a w określonych sytuacjach również możliwość zastosowania korekty technicznej.


Najważniejsze kody błędów i statusy KSeF 2.0 – tabela praktyczna 


Poniższa tabela ma charakter praktyczny. Zawiera najważniejsze kody błędów KSeF wraz z ich znaczeniem oraz rekomendowaną reakcją organizacyjną.


Kod / status

Warstwa odpowiedzi

Znaczenie praktyczne

Co sprawdzić / jak zareagować

400

Status HTTP

Nieprawidłowe żądanie albo błąd walidacji danych wejściowych.

Sprawdzić treść odpowiedzi, ExceptionCode, parametry endpointu, dane wejściowe i ewentualnie plik XML.

401

Status HTTP

Brak poprawnego uwierzytelnienia.

Zweryfikować token, certyfikat, sesję uwierzytelnienia i ważność tokena.

403

Status HTTP

Brak uprawnień albo niedozwolony kontekst działania.

Sprawdzić uprawnienia w KSeF, kontekst NIP oraz wymagane uprawnienia dla danej operacji.

410

Status HTTP

Operacja wygasła i nie jest już dostępna.

Ustalić, czy upłynął czas dostępności statusu, wniosku albo operacji; w razie potrzeby rozpocząć proces ponownie.

429

Status HTTP

Przekroczony limit żądań API.

Nie poprawiać faktury „na siłę”. Sprawdzić Retry-After, kolejkowanie zapytań, limity API i sposób działania integracji.

500 / 5xx

Status HTTP

Błąd techniczny po stronie usługi albo infrastruktury.

Zabezpieczyć logi i traceId, ponowić zgodnie z procedurą retry, monitorować komunikaty techniczne i kontaktować się z integratorem/MF, gdy problem się powtarza.

21111

ExceptionCode

Nieprawidłowe wyzwanie autoryzacyjne.

Sprawdzić challenge, sposób szyfrowania i czas użyty w procesie uwierzytelnienia.

21115

ExceptionCode

Nieprawidłowy certyfikat.

Zweryfikować certyfikat użyty do uwierzytelnienia, jego ważność i zgodność z wymaganiami KSeF.

21117

ExceptionCode

Nieprawidłowy identyfikator podmiotu dla wskazanego typu kontekstu.

Sprawdzić, czy NIP albo inny identyfikator pasuje do wybranego typu kontekstu.

21155

ExceptionCode

Przekroczono dozwoloną liczbę faktur w sesji.

Zamknąć bieżącą sesję albo otworzyć nową zgodnie z limitem dla danego trybu wysyłki.

21157

ExceptionCode

Nieprawidłowy rozmiar części pakietu.

Sprawdzić rozmiary części paczki przy wysyłce wsadowej i zgodność deklaracji z rzeczywistymi plikami.

21161

ExceptionCode

Przekroczono dozwoloną liczbę części pakietu.

Zweryfikować przygotowanie paczki wsadowej i limity liczby części.

21164

ExceptionCode

Faktura o podanym identyfikatorze nie istnieje.

Sprawdzić numer KSeF, dostęp do faktury i kontekst podmiotu, w którym wykonywane jest pobranie.

21165

ExceptionCode

Faktura o podanym numerze KSeF nie jest jeszcze dostępna.

Nie zakładać od razu błędu faktury; odczekać i ponowić pobranie zgodnie z logiką systemu.

21166

ExceptionCode

Korekta techniczna niedostępna.

Sprawdzić, czy dla faktury nie została już prawidłowo przetworzona korekta techniczna.

21167

ExceptionCode

Status faktury nie pozwala na korektę techniczną.

Ocenić status faktury; nie każda pomyłka może zostać obsłużona korektą techniczną.

21173

ExceptionCode

Brak sesji o wskazanym numerze referencyjnym.

Zweryfikować numer referencyjny sesji, środowisko i kontekst, w którym wykonywane jest zapytanie.

21175

ExceptionCode

Wynik zapytania o podanym identyfikatorze nie istnieje.

Sprawdzić referencję zapytania lub eksportu oraz czas dostępności wyniku.

21178

ExceptionCode

Nie znaleziono UPO dla podanych kryteriów.

Sprawdzić status sesji/faktury, numer referencyjny i moment generowania UPO.

21180

ExceptionCode

Status sesji nie pozwala na wykonanie operacji.

Sprawdzić, czy sesja nie została zamknięta, anulowana albo nie znajduje się w statusie blokującym dalszą operację.

21181

ExceptionCode

Nieprawidłowe żądanie eksportu faktur.

Zweryfikować kryteria eksportu, kontekst podmiotu i zakres danych, których dotyczy eksport.

21182

ExceptionCode

Osiągnięto limit trwających eksportów.

Odczekać albo ograniczyć liczbę równoległych eksportów dla danego kontekstu.

21183

ExceptionCode

Zakres filtrowania wykracza poza dostępny zakres danych.

Sprawdzić zakres dat, typ daty i ograniczenia dotyczące dostępnego zakresu danych.

21205

ExceptionCode

Pakiet nie może być pusty.

Przy wysyłce wsadowej sprawdzić czy przesłano wszystkie zadeklarowane części paczki.

21208

ExceptionCode

Przekroczono czas oczekiwania na upload albo finish.

Sesja wsadowa mogła zostać anulowana; sprawdzić czas wysyłki i ponowić proces zgodnie z procedurą.

21217

ExceptionCode

Nieprawidłowe kodowanie znaków.

Zweryfikować kodowanie dokumentu i sposób przygotowania danych wejściowych.

21301

ExceptionCode

Brak autoryzacji.

Sprawdzić status operacji uwierzytelniania, token KSeF i to, czy token nie został unieważniony.

21304

ExceptionCode

Brak uwierzytelnienia.

Sprawdzić numer referencyjny operacji uwierzytelniania i czy operacja istnieje w danym środowisku.

21308

ExceptionCode

Próba wykorzystania metod autoryzacyjnych osoby zmarłej.

Błąd szczególny po stronie autoryzacji; wymaga wyjaśnienia sposobu uwierzytelnienia.

21401

ExceptionCode

Dokument nie jest zgodny ze schemą XSD.

Sprawdzić plik XML względem właściwej struktury logicznej oraz komunikat walidatora.

21402

ExceptionCode

Nieprawidłowy rozmiar pliku.

Sprawdzić, czy deklarowany rozmiar pliku odpowiada rzeczywistej długości treści.

21403

ExceptionCode

Nieprawidłowy skrót pliku.

Zweryfikować hash pliku i sposób jego obliczenia.

21405

ExceptionCode

Błąd walidacji danych wejściowych.

Przeczytać szczegóły walidatora; ten kod wymaga analizy konkretnego komunikatu, nie samego numeru.

21406

ExceptionCode

Konflikt podpisu i typu uwierzytelnienia.

Sprawdzić metodę uwierzytelnienia i typ podpisu/certyfikatu użyty w danej operacji.

21418

ExceptionCode

Przekazany token kontynuacji ma nieprawidłowy format.

Sprawdzić token stronicowania/kontynuacji i nie modyfikować go ręcznie.

21470

ExceptionCode

Nieznany albo wycofany identyfikator klucza.

Sprawdzić publicKeyId i użycie aktualnego klucza publicznego MF dla danego środowiska.

25001

ExceptionCode

Brak możliwości pobrania danych do CSR dla wykorzystanego sposobu uwierzytelnienia.

Zweryfikować metodę uwierzytelnienia i uprawnienia użyte przy procesie certyfikatu KSeF.

25002

ExceptionCode

Brak możliwości złożenia wniosku certyfikacyjnego dla wykorzystanego sposobu uwierzytelnienia.

Sprawdzić, czy dana metoda uwierzytelnienia pozwala złożyć wniosek certyfikacyjny.

25003

ExceptionCode

Dane w CSR nie zgadzają się z danymi w wektorze uwierzytelniającym.

Zweryfikować dane w CSR i dane podmiotu wynikające z uwierzytelnienia.

25004

ExceptionCode

Niepoprawny format CSR albo niepoprawny podpis CSR.

Sprawdzić techniczne przygotowanie wniosku CSR, format i algorytm podpisu.

25005

ExceptionCode

Wniosek certyfikacyjny o podanym numerze referencyjnym nie istnieje.

Sprawdzić numer referencyjny wniosku i środowisko, w którym wykonywane jest zapytanie.

25006

ExceptionCode

Osiągnięto limit możliwych do złożenia wniosków certyfikacyjnych.

Zweryfikować limity certyfikatów i wniosków dla danego podmiotu/osoby.

25007

ExceptionCode

Osiągnięto limit dopuszczalnej liczby posiadanych certyfikatów.

Sprawdzić aktywne certyfikaty i potrzebę ich unieważnienia lub uporządkowania.

25010

ExceptionCode

Nieprawidłowy typ albo długość klucza.

Sprawdzić typ klucza, długość i zgodność z wymaganiami dokumentacji.

25011

ExceptionCode

Nieprawidłowy algorytm podpisu CSR.

Sprawdzić algorytm podpisu i funkcję skrótu zastosowaną w CSR.

26001

ExceptionCode

Nie można nadać tokenowi uprawnień, których podmiot nie posiada.

Sprawdzić faktyczne uprawnienia podmiotu i zakres uprawnień przypisywanych tokenowi.

26002

ExceptionCode

Nie można wygenerować tokena dla obecnego typu kontekstu.

Sprawdzić kontekst, w którym generowany jest token; token można generować tylko w dopuszczonym kontekście.

9101

ExceptionCode

Nieprawidłowy dokument.

Sprawdzić dokument użyty w procesie podpisu/uwierzytelnienia.

9102

ExceptionCode

Brak podpisu.

Zweryfikować, czy wymagany podpis został dołączony.

9103

ExceptionCode

Przekroczona liczba dozwolonych podpisów.

Sprawdzić liczbę podpisów i wymagania dla danego dokumentu.

Zestawienie opracowano na podstawie oficjalnej dokumentacji API KSeF 2.0, OpenAPI oraz materiałów technicznych MF/CIRF. Tabela ma charakter pomocniczy i nie zastępuje bieżącej weryfikacji dokumentacji technicznej.

Dlaczego sama lista kodów błędów KSeF to za mało?


Sama tabela kodów błędów może być pomocna, szczególnie przy pierwszej diagnozie problemu. Pozwala szybko ustalić, czy komunikat dotyczy autoryzacji, uprawnień, limitów API, sesji, tokenów, certyfikatów, pobierania faktur czy samego pliku XML.


Nie warto jednak traktować jej jako kompletnej instrukcji postępowania. W praktyce znaczenie ma również:


  • status HTTP,
  • treść odpowiedzi API,
  • status faktury,
  • moment procesu,
  • numer referencyjny,
  • traceId,
  • środowisko (testowe / produkcyjne).

Dokładnie ten sam numer błędu może oznaczać inne działania w zależności od kontekstu biznesowego.

profil-zaufany-czy-ulatwia-zalatwianie-spraw-ksiegowych-w-firmie

Jak praktycznie obsługiwać błędy KSeF?


Najbezpieczniejsze podejście to podejście procesowe. Przy każdym istotnym błędzie warto zabezpieczyć:


  • status HTTP,
  • pełną treść komunikatu,
  • ExceptionCode,
  • traceId,
  • numer referencyjny operacji,
  • status faktury,
  • numer KSeF (jeżeli został nadany).

Takie informacje znacząco przyspieszają analizę i ograniczają chaos organizacyjny pomiędzy księgowością, IT i dostawcą systemu.


Kody błędów KSeF a procedury wewnętrzne


Przy obowiązkowym KSeF obsługa błędów powinna stać się częścią procedury organizacyjnej.


W praktyce warto rozdzielić przynajmniej:


  1. błędy techniczne,
  2. błędy uwierzytelnienia,
  3. błędy XML i walidacji,
  4. błędy po przyjęciu faktury do KSeF,
  5. problemy z kodami QR i wizualizacją faktur.

Każda z tych sytuacji wymaga innej reakcji. Czasem wystarczy ponowić komunikację z systemem. Czasem trzeba poprawić dane w systemie źródłowym. Innym razem konieczna będzie analiza podatkowa albo działania dostawcy oprogramowania.


Poniżej wskazuję najważniejsze oficjalne źródła, z których warto korzystać przy weryfikacji komunikatów, statusów i kodów błędów KSeF 2.0.


FAQ

Prezentujemy najczęściej wyszukiwane pytania o błędy KSeF.

Zobacz również