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.
Błąd 401 Unauthorized (problem z tokenem)
Najczęstszy błąd przy próbie wysyłki. KSeF zwraca status HTTP 401 razem z komunikatem typu "Token nie istnieje lub stracił ważność". Możliwe przyczyny:
- Token został unieważniony w aplikacji Podatnika lub upłynął globalny termin (tokeny działają do końca 2026 r., potem trzeba używać certyfikatu KSeF).
- Token został odwołany przez właściciela w Portalu 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 nagłówku tokenu, czy wystawcą jest właściwy NIP.
Błąd 450: "Token cannot be used in nip-X context"
Najczęściej występuje w środowiskach testowych i demo KSeF (ap-test.ksef.mf.gov.pl, ap-demo.ksef.mf.gov.pl), choć zdarza się też w produkcji. Komunikat sugeruje problem z tokenem, ale w praktyce wskazuje na dane po stronie MF — niezarejestrowany lub „uszkodzony" NIP w bazie środowiska testowego.
Rozwiązanie: w teście najszybciej działa zmiana NIP-u na inny aktywny. W produkcji warto skontaktować się z MF przez formularz zgłoszeniowy KSeF. Pełen rozkład przyczyn, kroki diagnostyki i nasza własna historia walki z tym błędem są w dedykowanym przewodniku: Błąd 450 w KSeF: co naprawdę oznacza i jak go naprawić.
Błąd walidacji schematu FA(3)
Komunikat brzmi zwykle "Plik niezgodny ze schematem" i zawiera odniesienie do konkretnego pola. 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%" zamiast "23".
Rozwiązanie: uruchom walidację XML lokalnie zanim wyślesz fakturę do KSeF. FakturaFlow robi to automatycznie i pokazuje Ci dokładne miejsce błędu, po polsku, zanim plik opuści Twoje biuro. Szczegóły schematu znajdziesz w naszym artykule o schemacie FA(3).
Niepoprawny NIP w fakturze
KSeF weryfikuje, czy NIP istnieje w bazie podatników. Błąd "Podmiot nieaktywny" oznacza, że NIP albo nie istnieje, albo został wykreślony z rejestru VAT.
Rozwiązanie: przed wysyłką sprawdź NIP nabywcy w Białej Liście VAT. Jeśli NIP jest nieaktywny, klient nie ma prawa otrzymać faktury VAT (transakcja powinna być zafakturowana inaczej, np. jako sprzedaż nieopodatkowana). FakturaFlow wykonuje tę weryfikację automatycznie przed każdą wysyłką.
Niezgodność sumy: faktura odrzucona po wysyłce
Po wysyłce KSeF zwraca błąd typu "Suma kwot pozycji niezgodna z deklarowaną kwotą ogólną". To oznacza, że suma wartości brutto we wszystkich pozycjach (FaWiersz) różni się od pola P_15 nawet o ułamek grosza.
Najczęstsza przyczyna to zaokrąglenia. Faktura wystawiona w Excelu może pokazywać 100,00 zł, ale wewnętrznie przechowuje 99,995 zł. Po sumowaniu wynik różni się od oczekiwanego o grosz.
Rozwiązanie: przelicz fakturę na poziomie pojedynczych kwot zaokrąglonych do 2 miejsc po przecinku, a dopiero potem zsumuj je do P_15. FakturaFlow wymusza tę kolejność automatycznie.
UPO nie wraca po wysyłce
Wysyłka się powiodła, KSeF przyjął plik, ale UPO (Urzędowe Potwierdzenie 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 robi to automatycznie co 5 minut i powiadamia Cię o wyniku). 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 rozkład 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, ale oznacz je jako "do wysłania po awarii". FakturaFlow umieszcza je w kolejce i automatycznie wysyła, gdy wykryje, że KSeF znowu odpowiada. 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 wysyłka nadal zwraca 401. Najczęstsza przyczyna to brak nadania uprawnień nowemu tokenowi (klient wygenerował token, ale w innym kontekście NIP, np. dla działalności zamkniętej).
Rozwiązanie: poproś klienta, aby ponownie zalogował się do Portalu 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 naprawisz sam w 5 minut, jeśli wiesz, gdzie szukać. Trzecia wymaga cierpliwości i dobrej kolejki retry. Narzędzie, które automatycznie obsługuje wszystkie trzy (walidacja przed wysyłką, monitoring tokenów, ponawianie po awarii), oszczędzi Twojemu biuru kilka godzin tygodniowo.