Kody błędów KSeF: pełna lista z opisem i rozwiązaniem (API 2.8)

Program do faktur pokazuje „440” albo „415” i niewiele więcej. Krajowy System e-Faktur (KSeF) zgłasza problemy na czterech poziomach: przy fakturze, przy sesji wysyłki, przy logowaniu i w odpowiedzi HTTP. Ten sam numer znaczy na każdym z nich coś innego.

Klasyczne pułapki to 415, 435, 440 i 450. Kod 440 przy fakturze oznacza duplikat, a przy sesji jej anulowanie. Kod 450 przy fakturze to błąd w treści, a przy logowaniu błędny token KSeF. Kod 435 dotyczy raz pliku faktury, raz części paczki. Kod 415 ma aż trzy znaczenia.

Poziom rozpoznasz po dokładnym opisie. Podajemy opisy dosłownie, za Ministerstwem Finansów (MF), więc porównaj je z komunikatem w historii wysyłki lub w logu programu. Pomaga też moment. Błąd przed pierwszą fakturą to zwykle logowanie. Błąd jednej faktury to status faktury. Zatrzymana cała wysyłka to sesja albo HTTP.

Typowe sytuacje z przykładami opisujemy w tekście o najczęstszych błędach KSeF. Tu jest pełna lista z dokumentacji API KSeF 2.8 i uwagi z ponad 1 700 faktur wysłanych przez nas do produkcyjnego KSeF.

Jak czytać kod błędu KSeF

Status faktury. Każda faktura w sesji dostaje własny status z polami code, description i details. Kody 100, 150 i 200 to postęp i sukces. Wyższe znaczą, że ta jedna faktura nie przeszła. Inne z tej samej sesji mogły przejść.

Status sesji. Sesja interaktywna (online) przyjmuje faktury pojedynczo, wsadowa przyjmuje zaszyfrowaną paczkę ZIP. Status sesji dotyczy całej wysyłki: klucza szyfrowania, paczki, limitów i czasu.

Status logowania. Program loguje się tokenem KSeF albo certyfikatem. Wynik ma własne kody w polu status.code, w odpowiedzi z kodem HTTP 200. Dlatego 450 przy logowaniu nie jest kodem HTTP.

Odpowiedź HTTP. Gdy KSeF odrzuca samo żądanie, odpowiada kodem 400 z pięciocyfrowym kodem wyjątku 21xxx. Inne kody HTTP dotyczą dostępu i obciążenia: 401, 403, 410, 429 i 5xx.

Status faktury

To odpowiedź KSeF o jedną fakturę wysłaną w sesji. Po kodzie 200 faktura ma numer KSeF i własne Urzędowe Poświadczenie Odbioru (UPO).

Kod	Oficjalny opis	Co zrobić	Poradnik
100	„Faktura przyjęta do dalszego przetwarzania”	To nie błąd: faktura czeka w kolejce, sprawdź status za chwilę.	nie dotyczy
150	„Trwa przetwarzanie”	To nie błąd: odczekaj i sprawdź status ponownie.	nie dotyczy
200	„Sukces”	To nie błąd: faktura jest w KSeF, możesz pobrać jej UPO.	nie dotyczy
405	„Przetwarzanie anulowane z powodu błędu sesji”	Sprawdź status sesji, a fakturę wyślij ponownie w nowej sesji.	Błąd 405
410	„Nieprawidłowy zakres uprawnień”	Sprawdź, czy firma, w której program jest zalogowany, może wystawiać faktury za NIP sprzedawcy.	Błąd 410
415	„Brak możliwości wysyłania faktury z załącznikiem”	Fakturę z załącznikiem wyślij w sesji wsadowej, po zgłoszeniu tej opcji w e-Urzędzie Skarbowym.	Błąd 415
430	„Błąd weryfikacji pliku faktury”	Sprawdź plik XML: kodowanie UTF-8 bez BOM, zgodność ze schematem FA(3) i rozmiar.	Błąd 430
435	„Błąd odszyfrowania pliku”	KSeF nie odszyfrował pliku: to zwykle błąd szyfrowania w programie, nie treści faktury.	Błąd 435
440	„Duplikat faktury”	Nie wysyłaj ponownie: odpowiedź podaje numer KSeF faktury, która już jest w systemie.	Błąd 440
450	„Błąd weryfikacji semantyki dokumentu faktury”	Popraw treść według FA(3): KSeF nie wskazuje pola, typowe przyczyny są w poradniku.	Błąd 450
500	„Nieznany błąd ({statusCode})”	Odczekaj i sprawdź status ponownie, a powtarzający się błąd zgłoś do MF.	Błędy 500 i 550
550	„Operacja została anulowana przez system”, szczegół: „Przetwarzanie zostało przerwane z przyczyn wewnętrznych systemu. Spróbuj ponownie”	Wyślij fakturę ponownie, tak jak radzi sam komunikat.	Błędy 500 i 550

Przy 440 KSeF podaje numer KSeF i sesję oryginału (originalKsefNumber, originalSessionReferenceNumber). Duplikat to ten sam NIP sprzedawcy, rodzaj faktury (RodzajFaktury) i numer (P_2), przez 10 pełnych lat od końca roku wystawienia. Ten sam numer przy korekcie KOR duplikatem nie jest. Jeżeli program zgubił odpowiedź i wysłał fakturę drugi raz, 440 bywa dobrą wiadomością: faktura już jest w KSeF.

Dokumentacja MF wymienia, co KSeF sprawdza w fakturze: XML 1.0 w UTF-8 bez BOM, zgodność ze schematem, unikalność, datę wystawienia (P_1) nie późniejszą niż data przyjęcia, sumy kontrolne NIP-ów (tylko w produkcji), rozmiar (1 MB, z załącznikami 3 MB), szyfrowanie i uprawnienia. Kod błędu dokumentacja wiąże jednak wprost tylko z duplikatami. Wskazówki przy 405, 410, 415 i 430 to więc nasz wniosek z tych zasad, nie stanowisko MF. Sum kwot ani statusu VAT nabywcy KSeF według tego opisu nie sprawdza.

Z naszej praktyki: 24 września 2026 r. dostaliśmy 435 przy jednej fakturze. Winny był nasz program, nie faktura: szyfrowanie psuło plik, gdy jego długość była wielokrotnością 16 bajtów.

Status sesji

Kolumna „Sesja” mówi, czy kod dotyczy sesji wsadowej, interaktywnej, czy obu.

Kod	Sesja	Oficjalny opis	Co zrobić	Poradnik
100	wsadowa	„Sesja wsadowa rozpoczęta”	To nie błąd: program może wysyłać części paczki.	nie dotyczy
100	interaktywna	„Sesja interaktywna otwarta”	To nie błąd: program może wysyłać faktury.	nie dotyczy
150	wsadowa	„Trwa przetwarzanie”	To nie błąd: sprawdź status później.	nie dotyczy
170	interaktywna	„Sesja interaktywna zamknięta”	To nie błąd: UPO sesji pojawi się po jej przetworzeniu.	nie dotyczy
200	wsadowa	„Sesja wsadowa przetworzona pomyślnie”	To nie błąd: sprawdź jeszcze status każdej faktury i pobierz UPO.	nie dotyczy
200	interaktywna	„Sesja interaktywna przetworzona pomyślnie”	To nie błąd: sprawdź jeszcze status każdej faktury i pobierz UPO.	nie dotyczy
405	wsadowa	„Błąd weryfikacji poprawności dostarczonych elementów paczki”	Paczkę buduje program, więc zgłoś błąd jego dostawcy.	Błąd 405
415	obie	„Błąd odszyfrowania dostarczonego klucza”	KSeF nie odszyfrował klucza sesji: to błąd szyfrowania w programie, zgłoś go dostawcy.	Błąd 415
420	wsadowa	„Przekroczony limit faktur w sesji”	Podziel wysyłkę: sesja mieści domyślnie 10 000 faktur.	Błąd 420
430	wsadowa	„Błąd dekompresji pierwotnego archiwum”	Archiwum ZIP nie dało się rozpakować: zbuduj paczkę od nowa.	Błąd 430
435	wsadowa	„Błąd odszyfrowania zaszyfrowanych części archiwum”	Części paczki nie dały się odszyfrować: to błąd szyfrowania w programie.	Błąd 435
440	wsadowa	„Sesja anulowana”, szczegół: „Przekroczono czas wysyłki” albo „Nie przesłano faktur”	Wyślij paczkę w nowej sesji, w limicie 20 minut na każdą część.	Błąd 440
440	interaktywna	„Sesja anulowana”, szczegół: „Nie przesłano faktur”	Nic nie zginęło: w sesji nie było faktur, otwórz nową przy kolejnej wysyłce.	Błąd 440
445	obie	„Błąd weryfikacji, brak poprawnych faktur”	Żadna faktura nie przeszła: sprawdź status każdej z nich, tam jest właściwy kod.	Błąd 445
500	wsadowa	„Nieznany błąd ({statusCode})”	Odczekaj i sprawdź status ponownie, a powtarzający się błąd zgłoś do MF.	Błędy 500 i 550

Granice paczki wsadowej: najwyżej 50 części, każda do 100 MB przed zaszyfrowaniem, całość do 5 GB. Każda sesja mieści domyślnie 10 000 faktur. Na wysyłkę jest 20 minut na każdą część paczki. Sesja interaktywna zamyka się sama po 12 godzinach od utworzenia. Przy 405 i 445 dokumentacja podaje tylko opis, bez przyczyn, więc wskazówka przy 405 to nasz wniosek.

Status logowania

Te kody przychodzą w odpowiedzi o wynik logowania. Kody 100 i 200 nie są błędami.

Kod	Oficjalny opis	Co zrobić	Poradnik
100	„Uwierzytelnianie w toku”	To nie błąd: program sprawdzi wynik za chwilę.	nie dotyczy
200	„Uwierzytelnianie zakończone sukcesem”	To nie błąd: program może otworzyć sesję.	nie dotyczy
415	„Uwierzytelnianie zakończone niepowodzeniem”, szczegół: „Brak przypisanych uprawnień”	Token albo osoba nie ma uprawnień w tej firmie: nadaj je lub wygeneruj token z uprawnieniami.	Błąd 415
425	„Uwierzytelnienie unieważnione”, szczegół: „Uwierzytelnienie i powiązane refresh tokeny zostały unieważnione przez użytkownika”	Zaloguj się od nowa.	Błędy 460, 425 i 470
450	„Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu”	Odczytaj szczegół z listy niżej, zwykle pomaga nowy token dla właściwego NIP-u i środowiska.	Błąd 450
460	„Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu”	Odczytaj szczegół z listy niżej, a nieważny, odwołany lub zawieszony certyfikat zastąp nowym.	Błędy 460, 425 i 470
470	„Uwierzytelnianie zakończone niepowodzeniem”, szczegół: „Próba wykorzystania metod autoryzacyjnych osoby zmarłej”	Zaloguj się danymi innej osoby, która ma uprawnienia w tej firmie.	Błędy 460, 425 i 470
480	„Uwierzytelnienie zablokowane”, szczegół: „Podejrzenie incydentu bezpieczeństwa. Skontaktuj się z Ministerstwem Finansów przez formularz zgłoszeniowy.”	Napisz do MF przez formularz, tak jak każe komunikat.	Błąd 480
500	„Nieznany błąd”	Spróbuj zalogować się ponownie za chwilę.	Błędy 500 i 550
550	„Operacja została anulowana przez system”	Spróbuj zalogować się ponownie.	Błędy 500 i 550

Szczegóły przy kodzie 450 (KSeF podaje jeden z nich):

„Nieprawidłowe wyzwanie autoryzacyjne”
„Nieprawidłowy token”
„Nieprawidłowy czas tokena”
„Token unieważniony”
„Token nieaktywny”
„Nieprawidłowe szyfrowanie tokena”
„Nieprawidłowe kodowanie tokena”
„Token nie może być użyty w kontekście {contextIdentifier}”

Szczegóły przy kodzie 460 (KSeF podaje jeden z nich):

„Nieważny certyfikat”
„Błąd weryfikacji łańcucha certyfikatów”
„Niezaufany łańcuch certyfikatów”
„Certyfikat odwołany”
„Certyfikat zawieszony”
„Niepoprawny certyfikat”

Z praktyki: w szczególe dotyczącym kontekstu numer to NIP, o który program poprosił, a nie NIP właściciela tokenu. Token z produkcyjnej Aplikacji Podatnika nie zadziała w środowisku TEST ani DEMO, bo każde środowisko ma własne tokeny.

Kody wyjątków 21xxx (HTTP 400)

Specyfikacja API wymienia około 50 kodów 21xxx. Poniżej są te, które spotyka program wysyłający faktury. Przychodzą od razu, w odpowiedzi na konkretne żądanie, i zwykle mówią o samym żądaniu, nie o treści faktury.

Kod	Oficjalny opis	Co zrobić	Poradnik
21155	„Przekroczono dozwoloną liczbę faktur w sesji.”	Zamknij sesję i otwórz nową: limit wynosi domyślnie 10 000 faktur.	Limity sesji (420)
21157	„Nieprawidłowy rozmiar części pakietu.”	Sprawdź części paczki: każda może mieć do 100 MB przed zaszyfrowaniem.	Limity sesji (420)
21161	„Przekroczono dozwoloną liczbę części pakietu.”	Przebuduj paczkę: może mieć najwyżej 50 części.	Limity sesji (420)
21166	„Korekta techniczna niedostępna.”	Faktura ma już prawidłowo przetworzoną korektę techniczną, drugiej nie wyślesz.	Błędy 21166 i 21167
21167	„Status faktury nie pozwala na korektę techniczną.”	Faktura została prawidłowo przetworzona, więc korekty technicznej do niej nie wyślesz.	Błędy 21166 i 21167
21173	„Brak sesji o wskazanym numerze referencyjnym.”	Program podał numer sesji, której KSeF nie zna: otwórz nową sesję.	Błąd 21184 i pokrewne
21178	„Nie znaleziono UPO dla podanych kryteriów.”	Sprawdź numer KSeF i numer sesji, a tuż po wysyłce spróbuj ponownie po chwili.	Błąd 21178
21180	„Status sesji nie pozwala na wykonanie operacji.”	Sesja nie przyjmuje już faktur (na przykład zamknęła się po 12 godzinach): otwórz nową.	Błąd 21184 i pokrewne
21184	„Sesja tymczasowo niedostępna.”	Faktura jest w porządku: otwórz nową sesję i wyślij ją ponownie, tak zaleca MF.	Błąd 21184
21205	„Pakiet nie może być pusty.”	Paczka nie zawiera faktur: zbuduj ją od nowa.	Limity sesji (420)
21208	„Czas oczekiwania na requesty upload lub finish został przekroczony.”	Wyślij paczkę w nowej sesji, w limicie 20 minut na każdą część.	Limity sesji (420)
21402	„Nieprawidłowy rozmiar pliku.”	Rozmiar podany przez program nie zgadza się z plikiem: zgłoś to dostawcy programu.	Błędy 21402 i 21403
21403	„Nieprawidłowy skrót pliku.”	Skrót (hash) podany przez program nie zgadza się z plikiem: zgłoś to dostawcy programu.	Błędy 21402 i 21403
21405	„Błąd walidacji danych wejściowych.”	Przeczytaj szczegół: zwykle wskazuje błędne pole żądania, które musi poprawić program.	Błąd 21405
21470	„Przesłany identyfikator klucza jest nieznany lub wskazuje na wycofany klucz.”	Program musi pobrać aktualny certyfikat klucza publicznego MF i powtórzyć żądanie.	Błąd 21470

Kod 21184 dodała wersja 2.8.0 API, na produkcji od 23 września 2026 r. MF zaleca wprost: „Rekomendowane jest otwarcie nowej sesji i kontynuowanie wysyłki.” Korekta techniczna (21166, 21167) dotyczy tylko faktury z trybu offline, odrzuconej z przyczyn technicznych.

Dla programisty: szczegół przy 21405 to komunikat walidatora (u nas kiedyś 'encryption' must not be empty.). Przy 21470 pobierz ponownie GET /security/public-key-certificates, wybierz aktualny certyfikat dla danego usage i powtórz żądanie z nowym publicKeyId.

Kody HTTP

Kod	Oficjalny opis	Co zrobić	Poradnik
400	odpowiedź z kodem wyjątku 21xxx w polach `ExceptionCode`, `ExceptionDescription` i `Details`	Odczytaj kod 21xxx i znajdź go w tabeli wyżej.	opis wyżej
401	„Unauthorized”, przykładowy szczegół: „Wymagane jest uwierzytelnienie.”	Program nie jest zalogowany: zaloguj go ponownie, w razie potrzeby nowym tokenem.	Błąd 401
403	„Forbidden” z polem `reasonCode` (lista niżej)	Odczytaj `reasonCode`, bo to on mówi, czego brakuje.	Błąd 403
410	„Gone”, szczegół: „Operacja wygasła i nie jest już dostępna.”	Status logowania jest przechowywany 7 dni: zaloguj się od nowa.	Błąd 410
429	„Too Many Requests”	Odczekaj tyle sekund, ile podaje nagłówek `Retry-After`, faktura jest w porządku.	Błąd 429
500 i inne 5xx	ogólne kody HTTP błędu po stronie serwera	Spróbuj ponownie później, ale najpierw sprawdź, czy wysłana faktura nie trafiła już do KSeF.	Błędy 500 i 550

Wartości reasonCode przy 403:

missing-permissions: „Brak wymaganych uprawnień do wykonania operacji w bieżącym kontekście.”
ip-not-allowed: „Żądanie pochodzi z adresu IP innego niż wskazany podczas uwierzytelnienia.”
security-service-blocked: „Żądanie zostało zablokowane przez mechanizmy bezpieczeństwa.”
auth-method-not-allowed: „Ta operacja nie jest dostępna dla użytej metody uwierzytelnienia.”
insufficient-resource-access: „Brak dostępu do wskazanego zasobu.”
context-type-not-allowed: „Operacja nie jest dostępna dla uwierzytelnionego typu kontekstu.”

Przy wysyłce części paczki 401 oznacza „nieprawidłowe uwierzytelnienie”, a 403 „brak uprawnień do zapisu (np. upłynął czas na zapis)”.

Limity zapytań liczą się dla pary: firma (kontekst) i adres IP. Wysłanie faktury w sesji interaktywnej to najwyżej 10 zapytań na sekundę, 30 na minutę i 180 na godzinę. Od API 2.8 zamykanie sesji ma osobne, dwukrotnie wyższe limity niż otwieranie. DEMO ma limity takie jak produkcja, TEST dziesięć razy wyższe.

Błędy 5xx są zwykle chwilowe. Jeżeli jednak połączenie zerwało się po wysłaniu faktury, KSeF mógł ją przyjąć. Sprawdź wtedy listę faktur przyjętych w sesji, zanim wyślesz ją znowu.

Co sprawdzić najpierw

Ustal poziom. Porównaj opis z tabelami. Ten sam numer na innym poziomie to inny problem.
Sprawdź, czy faktura nie jest już w KSeF. Po zerwanym połączeniu lub błędzie 5xx zajrzyj do listy faktur przyjętych w sesji.
Kody chwilowe: 21184, 429, 5xx i 550. Nic nie poprawiaj. Odczekaj i ponów wysyłkę (przy 21184 w nowej sesji).
Sama faktura: 430, 450 i 440. Przy 430 i 450 popraw plik lub treść. Przy 440 nie wysyłaj ponownie, a innej fakturze z tym samym numerem nadaj nowy numer.
Dostęp: 415 przy logowaniu i przy załączniku, 410, 403 i 450 przy logowaniu. Zwykle winny jest token, certyfikat, uprawnienia lub zgoda na załączniki, nie treść faktury.
Program: 435, 415 sesji, 21402, 21403, 21405 i 21470. Wyślij dostawcy programu pełny komunikat ze szczegółami.
MF: 480 i 500, który wraca mimo ponowień. Napisz przez formularz zgłoszeniowy albo na jpk.helpdesk@mf.gov.pl.

FakturaFlow pokazuje każdy błąd KSeF po polsku, razem z tym, co poprawić. Przed wysyłką sprawdza fakturę według zasad FA(3), więc wiele odrzuceń nie dochodzi do KSeF. Przy chwilowej niedostępności, także przy 21184, sam ponawia wysyłkę w rosnących odstępach. W oknie „Szczegóły KSeF” widzisz historię statusów, numer KSeF i link do weryfikacji MF. Działa obok Twojego programu księgowego. Zobacz, jak to działa.

Podsumowanie

Kod KSeF czytaj zawsze razem z poziomem, z którego pochodzi. 440 przy fakturze to duplikat, a przy sesji anulowanie. 450 przy fakturze to treść, a przy logowaniu token. Kody chwilowe wymagają cierpliwości, a błędy szyfrowania i budowy żądania naprawia dostawca programu, nie biuro.

Oficjalne źródła

Opisy w tabelach pochodzą z dokumentacji API KSeF 2.0 publikowanej przez Centrum Informatyki Resortu Finansów, w stanie z 22 września 2026 r.

Stan na październik 2026 r. Opis na podstawie dokumentacji API KSeF 2.0 (wersja 2.8). Kody i komunikaty mogą się zmienić wraz z nowymi wersjami API.