Wprowadzenie
KSeF zgłasza problemy jako kody wyjątków w treści odpowiedzi, obok statusu HTTP — i to kod, a nie sam numer HTTP, mówi, co naprawdę się nie powiodło. Najczęstsze przyczyny to nieprawidłowe wyzwanie uwierzytelniające, nieprawidłowy certyfikat albo faktura, która nie przechodzi schematu FA(3) i jest następnie raportowana jako nieprawidłowo przetworzona. Zamiast zgadywać, porównaj polski opis z oficjalną tabelą kodów KSeF — ten sam numer potrafi znaczyć co innego w różnych endpointach.
Jak KSeF zgłasza błędy
KSeF to krajowa platforma e-fakturowania Ministerstwa Finansów. Gdy wywołanie się nie powiedzie, odpowiedź zawiera kod wyjątku, taki jak 21111 albo 21401, oraz opis po polsku. Te kody są udokumentowane w specyfikacji API KSeF i to one są wiarygodnym sygnałem dla logiki ponowień i dla zespołu wsparcia.
Kody uwierzytelniania
Błędy uwierzytelniania pojawiają się jako kody na endpointach autoryzacji. Na przykład 21111 oznacza nieprawidłowe wyzwanie autoryzacyjne (zarówno dla ścieżki z tokenem, jak i z XAdES), 21115 to nieprawidłowy certyfikat na ścieżce XAdES, a 21301 lub 21304 oznaczają brak albo utratę autoryzacji czy uwierzytelnienia — na przykład gdy token został unieważniony. Najpierw napraw poświadczenie albo wyzwanie, potem ponawiaj.
Kody faktury i sesji
Gdy jesteś już w sesji, pojawiają się inne kody. 21401 oznacza, że dokument nie jest zgodny ze schematem XSD — ale na endpointcie /v2/auth/xades-signature dotyczy dokumentu XAdES używanego w alternatywnej ścieżce uwierzytelniania certyfikatem, a nie faktury FA(3). 21155 to przekroczenie limitu faktur w sesji, 21173 — brak sesji o podanym numerze, 21180 — status sesji nie pozwala na operację, a 21184 — sesja tymczasowo niedostępna. Faktura FA(3), która nie przechodzi schematu, jest raportowana w statusie przetwarzania — pojawia się jako nieprawidłowo przetworzona na liście nieudanych faktur sesji — a nie jako wyjątek 21401 przy wysyłce.
Przypadek 422 w Notaly
422 w tym przepływie to nie kod KSeF. W Notaly oznacza, że dane nie przeszły własnej walidacji Notaly, zanim dotarły do KSeF — na przykład NIP sprzedawcy niezgodny z wartością sandbox 2745013933. Odpowiedzią jest poprawienie danych, a nie ponawianie tych samych.
Prosta kolejność diagnozy
Najpierw sprawdź kod i opis, potem działaj według kategorii: problem z poświadczeniem, ze schematem, z sesją albo z danymi. Przy timeoutach ponawiaj ze stabilnym kluczem idempotencji i zweryfikuj status faktury przed ponowną wysyłką, żeby nigdy nie stworzyć duplikatu.
FAQ
Co oznacza błąd 400 z KSeF? Błąd 400 niesie w treści odpowiedzi kod wyjątku opisujący konkretny problem, np. nieprawidłowe wyzwanie, nieprawidłowy certyfikat albo — na endpointcie XAdES — dokument niezgodny ze schematem.
Czy 422 to kod KSeF? Nie. W Notaly 422 oznacza, że dane nie przeszły własnej walidacji Notaly przed dotarciem do KSeF.
Zastrzeżenie
Notaly nie jest doradcą podatkowym, księgowym ani prawnym. Ten artykuł ma charakter informacyjny, nie stanowi porady podatkowej i może być nieaktualny. Ponosisz odpowiedzialność za własne rozliczenia VAT; w razie potrzeby skonsultuj się z wykwalifikowanym księgowym.
Źródła
Źródło: api-test.ksef.mf.gov.pl