Praca z KSeF, podobnie jak z każdym systemem rządowym, generuje powtarzalny zestaw błędów. Zebraliśmy najczęściej zgłaszane przez biura rachunkowe i pokazujemy, jak je rozpoznać oraz jak naprawić, bez czekania na helpdesk Ministerstwa Finansów. Część z nich bierze się nie z samego systemu, lecz z podziału odpowiedzialności między biurem a klientem — to opisujemy osobno w tekście o obowiązkach biura rachunkowego w 2026 r..
Każdy kod z osobna, z oficjalnym opisem i tym, co zrobić, znajdziesz w zestawieniu kodów błędów KSeF.
Problem z tokenem: odmowa logowania (450) albo błąd 401
Najczęstszy błąd przy próbie wysyłki. Zły, unieważniony albo nieaktywny token KSeF kończy logowanie statusem 450 z opisem „Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu” i szczegółem, na przykład „Token unieważniony” albo „Token nieaktywny”. Gdy program wysyła żądanie bez ważnego zalogowania, KSeF odpowiada HTTP 401 (błąd 401 w KSeF). Możliwe przyczyny:
- Token został unieważniony w Aplikacji Podatnika lub upłynął globalny termin (pierwotnie tokeny miały wygasnąć z końcem 2026 r.; według zapowiedzi MF z września 2026 r. metoda tokenowa zostaje, a tokeny wydane do końca 2026 r. mają działać do 30 listopada 2027 r., nowe zaś będą miały termin ważności).
- Token został odwołany przez właściciela w Aplikacji Podatnika.
- Token został wpisany z literówką lub uciętym fragmentem.
- Próba wysyłki w środowisku testowym z tokenem produkcyjnym (lub odwrotnie).
Rozwiązanie: poproś klienta o wygenerowanie nowego tokenu (instrukcja w naszym przewodniku po tokenach KSeF) i wklej go w miejsce starego. Sprawdź w treści tokenu (fragment nip-…), czy dotyczy właściwego NIP-u.
Błąd 450
„Błąd weryfikacji semantyki dokumentu faktury” oznacza, że plik jest technicznie poprawny, ale jego treść łamie zasady struktury FA(3). KSeF nie wskazuje pola, które za to odpowiada. Konkretną listę pól, od przestrzeni nazw po kolejność elementów pod Fa, zebraliśmy osobno: Błąd 450 w KSeF: jak ustalić, które pole faktury jest błędne.
Błąd walidacji schematu FA(3)
Dokumentacja MF nie podaje, jakim kodem KSeF odrzuca plik niezgodny ze schematem. Z opisu pasuje do tego status 430 „Błąd weryfikacji pliku faktury” (błąd 430 w KSeF). Najczęstsze warianty to:
- brakujące pole obowiązkowe (np.
KodWaluty), - pole o niepoprawnym typie danych (tekst tam, gdzie wymagana liczba),
- data w niewłaściwym formacie (musi być YYYY-MM-DD),
- NIP zawierający myślniki, spacje lub inne znaki niż 10 cyfr,
- stawka VAT zapisana jako
23%zamiast23.
Błędy stawki mają własny zestaw przyczyn, w tym niezgodność wiersza z koszykiem podsumowania. Rozpisaliśmy je w tekście o błędzie stawki VAT w KSeF.
Rozwiązanie: uruchom walidację XML lokalnie zanim wyślesz fakturę do KSeF. FakturaFlow sprawdza każdą fakturę pod kątem reguł FA(3) przed wysyłką, a każdy błąd KSeF pokazuje po polsku, z informacją, co poprawić. Szczegóły schematu znajdziesz w naszym artykule o schemacie FA(3).
Niepoprawny NIP w fakturze
W środowisku produkcyjnym KSeF sprawdza sumę kontrolną NIP-u sprzedawcy (Podmiot1), nabywcy (Podmiot2), podmiotu trzeciego (Podmiot3) i podmiotu upoważnionego. Faktura z NIP-em o błędnej sumie kontrolnej zostaje odrzucona. Zgodnie z dokumentacją weryfikacji faktur ta kontrola działa tylko w produkcji, więc w środowisku testowym taka faktura może przejść. KSeF nie sprawdza natomiast, czy nabywca jest czynnym podatnikiem VAT.
Rozwiązanie: przed wysyłką porównaj NIP z dokumentem źródłowym, bo najczęściej to literówka albo zamienione cyfry. Status VAT nabywcy sprawdzisz osobno w Białej Liście VAT, bo KSeF tego nie robi. FakturaFlow sprawdza format NIP-u i numeru VAT UE przed wysyłką.
Niezgodność sum: KSeF ją przyjmie, a to gorzej
Opisane w dokumentacji MF kontrole faktury obejmują między innymi format XML, zgodność ze schematem, unikalność numeru, datę wystawienia i sumę kontrolną NIP-u. Nie ma wśród nich arytmetyki kwot. Faktura, w której suma wierszy różni się od P_15 o grosz z powodu zaokrągleń, zwykle przejdzie przez KSeF i dostanie numer. Błąd wyjdzie dopiero u nabywcy albo przy uzgadnianiu rozliczeń, a wtedy pozostaje korekta.
Najczęstsza przyczyna to zaokrąglenia. Faktura wystawiona w Excelu może pokazywać 100,00 zł, ale wewnętrznie przechowywać 99,995 zł.
Rozwiązanie: zaokrąglaj pojedyncze kwoty do 2 miejsc po przecinku i dopiero potem je sumuj. FakturaFlow przed wysyłką sprawdza, czy netto plus VAT daje brutto, i zatrzymuje fakturę, w której kwoty się nie zgadzają.
UPO nie wraca po wysyłce
Wysyłka się powiodła, KSeF przyjął plik, ale UPO (Urzędowe Poświadczenie Odbioru) nie pojawia się w systemie. Możliwe przyczyny:
- system MF jest przeciążony i przetwarza paczki z opóźnieniem,
- plik został przyjęty, ale walidacja zawartości jest jeszcze w toku,
- wystąpiła awaria po stronie KSeF (publikowana na stronie statusu MF).
Rozwiązanie: w zdecydowanej większości przypadków UPO przychodzi w ciągu kilku minut. Jeśli nie wróci po 60 minutach, sprawdź status wysyłki przez API KSeF (FakturaFlow sprawdza to automatycznie w tle co dwie minuty i aktualizuje status faktury). Jeśli system MF zgłasza awarię, poczekaj na rozwiązanie. Plik zostaje w kolejce i automatycznie zostanie powtórnie sprawdzony.
Awaria KSeF: tryb offline
W przypadku niedostępności lub awarii KSeF Ministerstwo Finansów dopuszcza wystawianie faktur w trybie offline. Faktura nie dostaje wtedy od razu numeru KSeF (ten nadawany jest dopiero po dosłaniu jej do systemu), tylko kod QR do weryfikacji. Termin dosłania zależy od trybu: następny dzień roboczy dla offline24 i niedostępności, a 7 dni roboczych dla ogłoszonej awarii. Pełny podział trybów, terminów i wymagań (w tym certyfikat KSeF typu 2) opisujemy w osobnym przewodniku: KSeF nie działa? Tryby offline, awaria i niedostępność.
Rozwiązanie: nie zatrzymuj wystawiania faktur. Faktury w trybie offline wystawia program, który obsługuje kody QR dla tego trybu. Jeśli wysyłka do KSeF jedynie chwilowo się nie udaje, FakturaFlow zostawia fakturę w kolejce i ponawia wysyłkę w rosnących odstępach, więc faktura nie ginie (trybu offline z kodami QR FakturaFlow nie obsługuje). Komunikaty o aktualnych awariach znajdziesz na stronie komunikatów technicznych Ministerstwa Finansów.
Brak dostępu po wymianie tokenu klienta
Klient wygenerował nowy token, biuro go wkleiło, ale logowanie nadal się nie udaje. Najczęstsze przyczyny to token wygenerowany w innym kontekście NIP, np. dla innej firmy klienta (status 450 ze szczegółem „Token nie może być użyty w kontekście…”), albo token bez potrzebnych uprawnień (status 415 ze szczegółem „Brak przypisanych uprawnień”, opisany w tekście o błędzie 415 w KSeF).
Rozwiązanie: poproś klienta, aby ponownie zalogował się do Aplikacji Podatnika i sprawdził, czy aktywny kontekst NIP jest ten sam, dla którego prosiłeś o token. Token wygenerowany w kontekście innej firmy klienta nie zadziała.
Podsumowanie
Większość błędów KSeF dzieli się na trzy kategorie: problemy z tokenem, problemy ze schematem i problemy z dostępnością systemu MF. Pierwsze dwie zwykle naprawisz sam w kilka minut, jeśli wiesz, gdzie szukać. Trzecia wymaga cierpliwości i dobrej kolejki ponowień. Narzędzie, które sprawdza faktury przed wysyłką, od razu testuje zapisany token i samo ponawia wysyłkę po chwilowej niedostępności KSeF, oszczędzi Twojemu biuru sporo czasu. Pełną listę kodów znajdziesz w zestawieniu kodów błędów KSeF.