Błędy i statusy KSeF

Co może pojawić się w kolumnie „Status KSeF” na liście dokumentów, co każdy wpis oznacza i jak go naprawić.

Instrukcja integracji z KSeF Konfiguracja krok po kroku — od tokenu do pierwszej wysyłki KSeF Client 2.0 — opis funkcji Co robi każdy przycisk i przełącznik w programie

Kolumna „Status KSeF” na liście dokumentów pokazuje, co stało się z fakturą po kliknięciu „KSeF Synchronizacja”. Poniżej znajdziesz wszystkie wartości, jakie mogą się tam pojawić — od stanów prawidłowych, przez faktury zatrzymane przez sam program, po odrzucenia zwrócone przez Ministerstwo Finansów.

Kolumna pokazuje tylko początek komunikatu Mieści się w niej około 80 znaków. Pełny opis błędu znajdziesz w miejscach opisanych w punkcie 6.

1. Statusy poprawne

Te wartości oznaczają, że wszystko działa prawidłowo.

Co widaćKolorZnaczenie
(pusto)—Faktura nigdy nie była wysyłana do KSeF. Tak samo wygląda po użyciu opcji „Wyczyść dane KSeF”.
onlinezielonyFaktura wystawiona w trybie online KSeF.
przetwarzanapomarańczowyPrzyjęta przez KSeF, czeka na numer. Stan przejściowy — zwykle znika w kilka minut.
wysłanazielonyPrzyjęta, numer KSeF nadany. To stan docelowy.
Wskazówka Status „wysłana” pojawia się także przy duplikacie (kod 440), gdy program odczytał numer wcześniejszej wysyłki tej samej faktury. To nie jest błąd — dokument jest w KSeF.

2. Faktury pominięte przez program

Te wpisy powstają, zanim faktura pojedzie do KSeF — program sam ją zatrzymuje, bo wykrył coś, co najprawdopodobniej skończyłoby się odrzuceniem. To najczęstsza grupa i jedyna, na którą wpływają ustawienia opisane w punkcie 5.

W jakiej kolejności program sprawdza fakturę

Każda faktura przechodzi sześć kontroli, jedna po drugiej:

  1. 902 — data z innego miesiąca
  2. 901 — brak kursu waluty
  3. 903 — stawka VAT spoza konfiguracji
  4. 904 — nie ustalono kraju nabywcy
  5. 906 — samofakturowanie na fakturze własnej
  6. 905 — korekta do faktury bez numeru KSeF
⚠️ Dlaczego po naprawie pojawia się kolejny błąd Zatrzymanie na dowolnej kontroli kończy sprawdzanie tej faktury — następne już się nie wykonują. Dlatego po usunięciu jednej przyczyny przy kolejnej synchronizacji może wyskoczyć następna: faktura walutowa z nietypową stawką najpierw pokaże 901, a dopiero po uzupełnieniu kursu — 903.

Program przechodzi wtedy do następnej faktury, więc jedna wadliwa faktura nie blokuje pozostałych.

Co oznaczają poszczególne komunikaty

Co widać w kolumnieZnaczenieJak naprawić
błąd: Brak kursu waluty EUR… (901) Faktura walutowa bez kursu, a VAT rozliczany w Polsce. Wpisz kurs w polu Uwagi w formacie EUR=4.2650 i ponów synchronizację. Przy odwrotnym obciążeniu kurs nie jest wymagany — faktura przejdzie sama.
błąd: Data wystawienia … różni się od daty wysyłki… (902) Faktura z innego miesiąca niż dzień wysyłki (tryb offline24). Jeśli data jest poprawna — wyślij ją świadomie (patrz punkt 5). Pamiętaj o terminie dosłania dokumentu.
błąd: Stawka 7% nie istnieje w ustawieniach stawek VAT… (903) Na pozycji faktury jest stawka spoza konfiguracji programu. Dodaj ją w Konfiguracja → Stawki VAT albo popraw stawkę na pozycji faktury.
błąd: Nabywca … nie ma NIP-u z prefiksem ISO ani wpisu w kartotece… (904) Nie da się ustalić kraju nabywcy — do KSeF poszłoby KodKraju=PL. Dodaj kontrahenta do kartoteki z wypełnionym polem Państwo albo podaj NIP z prefiksem kraju (np. DE123456789).
błąd: Faktura pierwotna … nie została jeszcze przyjęta przez KSeF… (905) Korekta do faktury, która nie ma jeszcze numeru KSeF. Nic nie rób. Program ponowi ją automatycznie, gdy oryginał dostanie numer.
błąd: Faktura ma adnotację samofakturowanie… (906) Sprzeczność — samofakturowanie oznacza fakturę wystawianą przez nabywcę. KSeF odrzuciłby ją. Usuń adnotację w polu Wycena i ponów synchronizację.

Kiedy program przepuszcza fakturę mimo wykrytego problemu

W kilku sytuacjach kontrola celowo nie zatrzymuje dokumentu:

KontrolaFaktura przechodzi mimo wszystko, gdy…
901 (kurs waluty)rozliczenie to odwrotne obciążenie lub „podatek rozlicza nabywca” — kurs nie jest wtedy potrzebny, bo VAT rozlicza nabywca
903 (stawka VAT)stawka to oznaczenie o zerowym VAT: NP, NP I, NP II, O.O. — nie muszą istnieć w tabeli stawek, bo nie ma czego przeliczać
904 (kraj nabywcy)kontrahent jest w kartotece z wypełnionym polem Państwo, albo dokument nie jest eksportowy / WDT / OSS — nabywca krajowy bez NIP to normalny przypadek
⚠️ Synchronizacja w tle działa inaczej Gdy synchronizacja idzie w tle, bez widocznego okna, kontrole 901, 903 i 904 przepuszczają fakturę z wpisem do dziennika — zamiast zatrzymywać cały proces oknem, na które nie ma kto kliknąć.

Wyjątkiem jest 902 (data z innego miesiąca) — ta zawsze pomija fakturę. Tryb offline24 nakłada obowiązek dosłania dokumentu w określonym terminie, więc cicha wysyłka byłaby decyzją podjętą za użytkownika.

3. Błędy zwrócone przez KSeF

Te powstają po wysyłce — dokument dotarł do Ministerstwa Finansów i został tam odrzucony.

Co widać w kolumnieZnaczenieJak naprawić
błąd: Brak uprawnien — NIP sprzedawcy … rozni sie od NIP w konfiguracji… Kod 410. NIP na fakturze nie zgadza się z NIP-em, na który zalogowany jest KSeF Client. Zrównaj Dane podatnika w programie z NIP-em w konfiguracji KSeF Client.
błąd: Faktura odrzucona przez KSeF / niezgodna ze schematem… KSeF przyjął resztę paczki, a tę fakturę odrzucił. Zwykle chodzi o zbyt długą nazwę pozycji. Nazwy towarów i usług: maksymalnie 256 znaków, bez przejść do nowej linii. Pomaga opcja „Ogranicz długość nazwy” (punkt 5).
błąd: Duplikat — faktura juz byla wyslana Kod 440. Faktura już jest w KSeF. Nic nie trzeba robić. Jeśli brakuje numeru na liście — użyj „Pobierz UPO” w oknie Przeglądaj faktury KSeF.
błąd: Duplikat — brak numeru KSeF Kod 440, ale system nie podał numeru pierwotnego dokumentu. Odszukaj fakturę w oknie Przeglądaj faktury KSeF i sprawdź numer ręcznie.
błąd: Blad wysylki batch Cała paczka odrzucona, serwer nie podał szczegółów. Sprawdź połączenie z internetem, zajrzyj do dziennika i ponów synchronizację.
błąd wysyłania Wysyłka nieudana, bez informacji o przyczynie. Otwórz plik .error i dziennik — w kolumnie nie ma nic więcej.

Kody odrzucenia po stronie Ministerstwa Finansów

KodZnaczenie
410brak uprawnień do wystawiania faktur na ten NIP
422błąd walidacji — plik nie spełnia wymagań schematu
430nieprawidłowy plik XML (uszkodzony lub z niewłaściwym kodowaniem)
440duplikat — faktura już jest w KSeF
450niezgodność semantyczna — dane w fakturze wykluczają się wzajemnie

Dodatkowo z warstwy logowania mogą pojawić się: 401 (token wygasł), 403 (brak uprawnień do NIP), 429 (przekroczony limit zapytań), 500 (błąd wewnętrzny KSeF), 503 (serwis niedostępny).

Odrzucenie wykryte po czasie Faktura potrafi wisieć jako „przetwarzana”, choć KSeF już ją odrzucił. Program co jakiś czas sprawdza takie dokumenty i wtedy podmienia status na „błąd: …” z właściwym kodem. Nie trzeba nic robić — wystarczy poczekać na kolejne sprawdzenie albo uruchomić synchronizację.

4. Pusta kolumna mimo braku wysyłki

Są dwa przypadki, w których dokument nie trafia do KSeF, ale kolumna zostaje pusta — bo nie powstaje żaden plik z opisem błędu. Łatwo je przeoczyć, szukając informacji wyłącznie w kolumnie.

SytuacjaGdzie to widaćCo zrobić
Nie udało się zbudować pliku faktury tylko okno synchronizacji: BLAD generowania: <numer> oraz dziennik ksef_sync.log Sprawdź opis błędu w dzienniku — zwykle chodzi o brakujące lub niepoprawne dane na fakturze.
Limit 500 faktur na jedną synchronizację okno synchronizacji: Wyslano 500 z N faktur. Pozostalo … Uruchom synchronizację ponownie — reszta pojedzie w kolejnych partiach.

Faktury pominięte i odroczone (kody 901–906) trafiają do licznika błędów w podsumowaniu synchronizacji — z punktu widzenia użytkownika każda z nich to dokument, którego w KSeF nie ma.

5. Ustawienia wpływające na błędy

„Wycisz komunikaty o błędach” (zakładka Inne)

Dotyczy wyłącznie kodów 901–904. Kody 905 i 906 są zawsze ciche, a błędy z punktu 3 przychodzą z serwera i tej opcji nie podlegają. Domyślnie opcja jest włączona.

StanZachowanie przy kodach 901–904
Włączone (domyślnie) Program nie pyta — pomija fakturę tak, jakby kliknięto „Nie”. Wpis trafia do kolumny, okna synchronizacji, dziennika i pliku z opisem błędu. Opis kończy się wtedy słowami „komunikat wyciszony, sprawdź KSeF Client / zakładka Inne”.
Wyłączone Przy każdej takiej fakturze pojawia się pytanie Tak / Nie / Anuluj.

Znaczenie odpowiedzi w oknie pytania:

  • Tak — wyślij tę fakturę mimo ostrzeżenia i przejdź dalej
  • Nie — pomiń tę jedną fakturę, kontynuuj z następnymi
  • Anuluj — przerwij całą synchronizację; nieprzetworzone faktury zostają nietknięte
Kiedy warto wyłączyć wyciszenie Gdy chcesz wysłać faktury z poprzedniego miesiąca (902) albo walutowe bez kursu (901) — to jedyna droga, żeby odpowiedzieć „Tak” i przepchnąć taki dokument. Wyciszenie włączono domyślnie, bo przy większej partii trzeba było klikać kilkadziesiąt okien.

„Tylko zaznaczone” — zaznaczenie faktur przed synchronizacją

Zaznaczenie konkretnych faktur na liście i kliknięcie KSeF Synchronizacja wyłącza wyciszenie niezależnie od ustawienia w KSeF Client.

Powód jest prosty: ręczne zaznaczenie to jawna deklaracja „chcę wysłać właśnie te”. Ciche pominięcie działałoby wbrew użytkownikowi — faktura zniknęłaby bez śladu w oknie.

💡 Praktyczny wniosek Żeby wysłać fakturę zatrzymaną przez kontrole 901–904 bez zmiany ustawień — zaznacz ją na liście, włącz „Tylko zaznaczone”, kliknij synchronizację i odpowiedz „Tak”.

Drugi efekt zaznaczenia: pomijany jest filtr daty początkowej, więc można wysłać dokument starszy niż domyślne okno synchronizacji.

Wszystkie kombinacje w jednej tabeli

Co stanie się z fakturą zatrzymaną przez kontrolę 901–904:

WyciszenieZaznaczone fakturyOkno synchronizacjiZachowanie
włączoneniewidocznepomija po cichu, zapisuje wpis w kolumnie
włączonenieukryte901/903/904 przepuszczają; 902 pomija
włączonetakwidocznepyta Tak / Nie / Anuluj — zaznaczenie unieważnia wyciszenie
wyłączoneniewidocznepyta Tak / Nie / Anuluj
wyłączonenieukryte901/903/904 przepuszczają; 902 pomija
wyłączonetakwidocznepyta Tak / Nie / Anuluj

Kontrole 905 i 906 pomijają zawsze, niezależnie od każdej kolumny w tej tabeli.

Jak poznać, kto pominął fakturę Ślad w kolumnie powstaje tak samo przy wyciszeniu, jak i po kliknięciu „Nie” — różni się tylko końcówka opisu: „komunikat wyciszony, sprawdź KSeF Client / zakładka Inne” kontra „pominięta na Twoje życzenie (kliknięte Nie)”.

Pozostałe ustawienia

OpcjaGdzieWpływ na błędy
Ogranicz długość nazwy towaru/usługi (256 znaków) zakładka Inne, domyślnie włączone Zapobiega odrzuceniu przez KSeF z powodu zbyt długiej nazwy pozycji. Zostaw włączone.
Pomiń eksport faktur do KSeF zakładka Główna Całkowicie wstrzymuje wysyłkę — żadna faktura nie pojedzie i żaden status się nie zmieni. Jeśli kolumna nie aktualizuje się mimo synchronizacji, sprawdź to pole w pierwszej kolejności.

6. Gdzie znaleźć pełną treść błędu

Kolumna pokazuje tylko pierwsze 80 znaków opisu. Całość znajdziesz w trzech miejscach:

MiejsceCo zawiera
C:\RAFSOFT\KSEF\{NIP}\error\<nazwa faktury>.error pola ERROR_CODE, ERROR_MESSAGE, ERROR_DETAILS
C:\RAFSOFT\KSEF\ksef_sync.log po jednej linii na fakturę, z kodem i opisem
okno synchronizacji wiersze POMINIETO i ODROCZONO z pełnym wyjaśnieniem, w trakcie wysyłki
⚠️ Warto wiedzieć
  • Statusy błąd: … nie są kolorowane na czerwono po ponownym otwarciu listy — czerwień widać wyłącznie w trakcie samej synchronizacji.
  • Pliki z opisem błędu dla kodów 901–906 są informacyjne — nie blokują ponowienia. Po usunięciu przyczyny następna synchronizacja wyśle fakturę normalnie.
  • Kolumna wyświetla dokładnie to, co zapisano przy fakturze, więc mogą trafić się wartości spoza tej listy — na przykład status przysłany z panelu mobilnego.

Nie znalazłeś swojego błędu?

FAQ — najczęstsze pytania o KSeF 2.0

Komentarze

Masz pytanie albo sugestię? Zostaw komentarz — adres e-mail jest wymagany, ale nie będzie publikowany. Komentarze pojawiają się po zatwierdzeniu przez moderatora.

Wysłanie komentarza oznacza zgodę na publikację jego treści i podanej nazwy użytkownika na tej stronie. Adres e-mail służy wyłącznie do celów administracyjnych i nie jest nikomu udostępniany.