Kody błędów KSeF

Przegląd

Kiedy KSeF (Krajowy System e-Faktur) odrzuca żądanie — logowanie, wysyłkę faktury albo jej korektę — odpowiada numerycznym kodem błędu. Ten sam kod może pojawić się w różnych programach do fakturowania, nie tylko w Biurku, bo pochodzi z samej bramki KSeF, a nie z aplikacji, przez którą się z nią łączysz.

Kody są pogrupowane tematycznie: logowanie i sesja, uprawnienia, poprawność struktury dokumentu, logika samej faktury i wreszcie awarie po stronie KSeF. Znajdź swój kod w odpowiedniej grupie, przeczytaj, co zwykle go powoduje, i sprawdź proponowane kroki. Część z nich da się naprawić samodzielnie w kilka minut, inne wymagają kontaktu z administratorem KSeF w Twojej firmie albo po prostu odczekania.

Logowanie i sesja

21100 — nieprawidłowy token autoryzacyjny

KSeF nie rozpoznał tokenu, którym próbujesz się uwierzytelnić. Token mógł zostać błędnie skopiowany, unieważniony w portalu KSeF albo wygenerowany dla innego środowiska (produkcyjnego zamiast testowego lub odwrotnie). Sprawdź, czy token pochodzi z właściwego środowiska i czy nie został wcześniej odwołany, a jeśli to nie pomoże — wygeneruj nowy token w portalu KSeF i podłącz go ponownie.

21115 — certyfikat odrzucony przez KSeF

To najczęstszy i zarazem najbardziej mylący błąd z całej listy, bo sam komunikat nie mówi wprost, co dokładnie poszło nie tak — może chodzić o jedną z trzech różnych przyczyn. Zanim zaczniesz szukać dalej, przejdź po kolei przez każdą z nich:

• Certyfikat nie jest zarejestrowany w KSeF. Sam fakt posiadania wygenerowanego certyfikatu nie wystarcza — musi on zostać wcześniej powiązany z Twoją firmą jako metoda uwierzytelniania w systemie KSeF. Jeśli tego kroku nie było (albo certyfikat powstał z inną opcją niż uwierzytelnianie w KSeF), system certyfikatu po prostu nie rozpozna.
• NIP w certyfikacie nie zgadza się z NIP-em firmy. Certyfikat wystawiony na inny podmiot (np. na dane osobiste zamiast na firmę, albo na inny numer identyfikacji podatkowej) zostanie odrzucony, nawet jeśli technicznie jest ważny.
• Jest już otwarta inna aktywna sesja z tym samym certyfikatem. KSeF nie zawsze pozwala na równoległe sesje z jednego certyfikatu — jeśli ten sam certyfikat jest już użyty gdzie indziej (inne urządzenie, inna aplikacja, zapomniana zakładka), nowa próba logowania zostanie zablokowana.

Co zrobić: sprawdź w portalu KSeF, czy certyfikat jest zarejestrowany i na jaki NIP; jeśli sesja rzeczywiście wisi gdzieś otwarta, odczekaj na jej wygaśnięcie albo zamknij ją ręcznie, zanim spróbujesz ponownie.

21175 — wyzwanie KSeF wygasło

Proces logowania do KSeF przebiega dwuetapowo: najpierw system wydaje tzw. wyzwanie (challenge), które trzeba podpisać w ograniczonym czasie. Jeśli między pobraniem wyzwania a jego podpisaniem minęło zbyt dużo czasu — na przykład z powodu wolnego połączenia albo przerwy w trakcie logowania — wyzwanie traci ważność. Rozwiązanie jest jedno: zacznij proces logowania od nowa.

21177 — sesja już otwarta dla tego certyfikatu

Ten sam certyfikat próbuje otworzyć drugą sesję, podczas gdy poprzednia wciąż jest aktywna. Zdarza się to, gdy poprzednie połączenie nie zostało poprawnie zamknięte — na przykład po zamknięciu karty przeglądarki bez wylogowania albo po przerwaniu procesu przez awarię łącza. Odczekaj, aż poprzednia sesja wygaśnie sama, albo jeśli masz do niej dostęp — zamknij ją ręcznie, zanim spróbujesz połączyć się ponownie.

21178 — sesja nie istnieje lub została zamknięta

Próbujesz użyć sesji, która już nie działa: albo nigdy nie została poprawnie otwarta, albo wygasła, albo ktoś (albo coś) ją wcześniej zamknął. Zwykle wystarczy połączyć się z KSeF od nowa — nowa sesja zastąpi tę nieaktualną.

21179 — przekroczony limit otwartych sesji

KSeF ogranicza liczbę jednocześnie otwartych sesji. Gdy limit zostanie wyczerpany — na przykład przy dużej liczbie równoległych połączeń z tej samej firmy — kolejne próby logowania są tymczasowo odrzucane. To zwykle stan przejściowy: odczekaj kilka minut i spróbuj ponownie, a jeśli błąd powtarza się regularnie, warto sprawdzić, czy jakieś stare sesje nie zostały porzucone otwarte.

21401 — token sesji nieważny lub wygasł

Token, którym posługuje się już otwarta sesja, przestał być ważny. Sesje KSeF mają ograniczony czas życia, więc jeśli operacja (np. wysyłka faktury) nastąpiła długo po zalogowaniu, token mógł wygasnąć w międzyczasie. Połącz się z KSeF ponownie, aby uzyskać świeży token.

21402 — token sesji odwołany

Token sesji został unieważniony — ręcznie, przez samego użytkownika, albo automatycznie przez KSeF w reakcji na inne zdarzenie (np. wykrycie podejrzanej aktywności albo zamknięcie sesji z innego miejsca). Odwołanego tokenu nie da się przywrócić — trzeba założyć nową sesję od zera.

21404 — tożsamość w tokenie nie pasuje do inicjatora sesji

Token sesji został wydany dla innej tożsamości (innego NIP-u lub innego certyfikatu) niż ta, która teraz próbuje go użyć. Zwykle to znak, że token został użyty w niewłaściwym kontekście — na przykład skopiowany między połączeniami dla różnych firm. Upewnij się, że token i certyfikat/NIP, którym się posługujesz, pochodzą z tej samej sesji logowania.

Uprawnienia

21330 — brak uprawnień do wystawienia faktury w imieniu sprzedawcy

Konto lub certyfikat, którym się łączysz, nie ma w KSeF uprawnienia do wystawiania faktur w imieniu tej firmy. Dzieje się tak najczęściej, gdy uprawnienia w portalu KSeF nadał ktoś inny i zapomniał dodać rolę wystawiania faktur, albo gdy uprawnienie zostało cofnięte. Sprawdź nadane uprawnienia w portalu KSeF (zakładka zarządzania uprawnieniami) i w razie potrzeby poproś administratora firmy o ich uzupełnienie.

21331 — brak uprawnień do odczytu faktur dla tego NIP-u

Podobna sytuacja, ale dotyczy odczytu — konto nie ma prawa pobierać ani przeglądać faktur wystawionych na wskazany NIP. Zwykle oznacza to, że uprawnienie do odczytu nie zostało nadane albo dotyczy innego zakresu (np. tylko własnych faktur, a nie faktur kontrahenta). Rozwiązanie jest takie samo jak wyżej: sprawdzić i uzupełnić uprawnienia w portalu KSeF.

Poprawność struktury dokumentu

Ta grupa obejmuje błędy zgłaszane, zanim KSeF w ogóle zdąży ocenić sens biznesowy faktury — system najpierw sprawdza, czy plik jest poprawnie zbudowany według wymaganego schematu XSD (formalnego wzorca struktury dokumentu XML).

21301 — faktura nie przeszła walidacji XSD

Struktura pliku faktury nie zgadza się z formalnym schematem XSD, którego wymaga KSeF — brakuje elementu, kolejność sekcji jest nieprawidłowa albo któryś fragment ma zły typ danych. Ten błąd zwykle wskazuje na problem po stronie generowania dokumentu, a nie na błąd wprowadzony ręcznie przez użytkownika. Jeśli korzystasz z gotowego programu do fakturowania, zgłoś to jako błąd do dostawcy; jeśli budujesz XML samodzielnie, porównaj dokument ze schematem FA(2)/FA(3) publikowanym przez Ministerstwo Finansów.

21302 — niepoprawny format numeru faktury

Numer faktury nie spełnia wymagań formalnych KSeF — na przykład zawiera niedozwolone znaki albo przekracza dopuszczalną długość. Sprawdź szablon numeracji faktur i upewnij się, że nie zawiera on znaków specjalnych spoza dozwolonego zestawu.

21303 — brakujące pole wymagane

W dokumencie brakuje pola, które KSeF traktuje jako obowiązkowe dla danego typu faktury — może to być dowolne pole, którego wymaga schemat: od danych kontrahenta po element podsumowania. Sprawdź, które dokładnie pole zgłasza błąd (komunikat zwykle je wskazuje), i uzupełnij brakującą wartość przed ponowną wysyłką.

21304 — niepoprawny NIP nabywcy lub sprzedawcy

NIP jednej ze stron transakcji nie przeszedł walidacji — jest zbyt krótki, zbyt długi, zawiera niedozwolone znaki albo nie ma poprawnej sumy kontrolnej. Zdarza się to często przy ręcznym wprowadzaniu danych kontrahenta. Sprawdź NIP w rejestrze GUS albo VIES (jeśli to kontrahent zagraniczny) i popraw literówkę.

21305 — niepoprawna data wystawienia faktury

Data wystawienia jest niezgodna z wymaganiami KSeF — na przykład wskazuje na przyszłość albo ma nieprawidłowy format. Sprawdź, czy data jest zapisana w oczekiwanym formacie (ISO 8601: rok-miesiąc-dzień) i czy nie wykracza poza dopuszczalny zakres.

21306 — niepoprawne wartości stawek VAT

Jedna ze stawek VAT na fakturze nie należy do zbioru wartości dopuszczalnych przez KSeF (np. 23%, 8%, 5%, 0%, zwolnione, „np" — nie podlega). Sprawdź pozycje faktury i upewnij się, że każda stawka jest jedną z wartości przewidzianych w schemacie, a nie np. zaokrągloną liczbą wpisaną ręcznie.

21307 — niepoprawny kod waluty

Kod waluty nie jest zgodny ze standardem ISO 4217 (trzyliterowym, np. PLN, EUR, USD) albo w ogóle go brakuje. Sprawdź, czy pole waluty zawiera poprawny trzyliterowy kod, a nie np. symbol waluty albo jej pełną nazwę.

21308 — brak pozycji na fakturze

Dokument nie zawiera ani jednej pozycji (linii towaru lub usługi), a KSeF wymaga co najmniej jednej. Zwykle to błąd generowania dokumentu — sprawdź, czy proces tworzenia faktury rzeczywiście dołączył pozycje przed wysyłką.

21309 — niepoprawny kurs waluty

Faktura w walucie obcej wymaga podania kursu przeliczeniowego na złote, a podany kurs jest nieprawidłowy — na przykład ma zły format liczbowy albo nie odpowiada dacie, dla której powinien zostać zastosowany. Sprawdź, czy kurs jest zapisany jako liczba dziesiętna i pochodzi z właściwego dnia (zwykle dnia poprzedzającego wystawienie faktury, zgodnie z tabelą kursów NBP).

21310 — suma kontrolna faktury (HashFA) nie zgadza się

Suma kontrolna dołączona do dokumentu nie odpowiada rzeczywistej zawartości pliku — plik został zmieniony po jej wyliczeniu albo sama suma została policzona błędnym algorytmem. To błąd techniczny po stronie generowania dokumentu: sprawdź, czy suma kontrolna jest liczona dokładnie z tej samej treści pliku, która trafia do wysyłki, bez żadnej modyfikacji pomiędzy tymi krokami.

Logika dokumentu

Te błędy pojawiają się, gdy struktura faktury jest poprawna, ale sama operacja nie ma sensu w kontekście tego, co już wie o niej KSeF.

21501 — faktura o tym numerze już wysłana

KSeF już przyjął fakturę o identycznym numerze od tego samego wystawcy i odrzuca próbę ponownego wysłania jej jako nowego dokumentu. Zwykle to znak podwójnej wysyłki — na przykład ponowienie żądania po tym, jak poprzednie zakończyło się sukcesem, ale odpowiedź nie dotarła do nadawcy. Sprawdź w historii wysyłek, czy faktura o tym numerze rzeczywiście już ma nadany numer KSeF; jeśli tak, nic więcej wysyłać nie trzeba.

21502 — numer KSeF nie istnieje w systemie

Odwołujesz się do numeru KSeF, którego system nie zna — literówka w numerze, numer z innego środowiska (np. testowego zamiast produkcyjnego) albo numer faktury, która nigdy nie została faktycznie przyjęta. Sprawdź numer znak po znaku i upewnij się, że pytasz o niego we właściwym środowisku KSeF.

21503 — faktura korygowana nie istnieje w KSeF

Korekta odwołuje się do faktury pierwotnej, której KSeF nie znajduje pod podanym numerem. Sprawdź pole z numerem KSeF faktury pierwotnej w dokumencie korekty — najczęstsza przyczyna to literówka albo pomylenie numeru KSeF z wewnętrznym numerem faktury nadanym przez program do fakturowania (to dwa różne numery).

21504 — nie można skorygować faktury już skorygowanej do zera

Faktura, do której odnosi się korekta, została już wcześniej w całości wyzerowana inną korektą — kolejna korekta tego samego dokumentu nie ma więc czego zmieniać. Sprawdź historię korekt tej faktury: jeśli saldo już wynosi zero, nowa korekta musi dotyczyć innego dokumentu albo innego zdarzenia gospodarczego.

Niedostępność i awarie

21900 — KSeF tymczasowo niedostępny

System KSeF nie odpowiada — trwa planowana przerwa techniczna, krótkotrwały problem po stronie usługi albo zwykłe obciążenie w godzinach szczytu. To nie jest błąd po stronie Twojego dokumentu ani Twoich danych: wystarczy odczekać i spróbować ponownie. W Biurku wysyłki w takiej sytuacji trafiają automatycznie do kolejki i są ponawiane bez dodatkowej akcji użytkownika.

21901 — tryb awaryjny KSeF aktywny

KSeF przełączył się w tryb awaryjny — w takiej sytuacji faktury można (i trzeba) wystawiać offline, poza systemem, a do KSeF trafiają dopiero po przywróceniu jego działania. Terminy dosłania zależą od trybu awarii:

• Przy trybie offline24 fakturę trzeba przesłać do KSeF najpóźniej następnego dnia roboczego po dniu jej wystawienia.
• Przy trybie awaryjnym (dłuższa niedostępność ogłoszona komunikatem Ministerstwa Finansów) na przesłanie faktur jest 7 dni roboczych liczonych od zakończenia awarii.

Faktura wystawiona w trybie offline jest ważna od razu — nie trzeba czekać na jej przyjęcie przez KSeF, żeby np. przekazać ją kontrahentowi. Dopilnuj tylko terminu dosłania właściwego dla ogłoszonego trybu awarii.

21999 — nieoczekiwany błąd KSeF

Błąd, który nie mieści się w żadnej ze znanych, nazwanych kategorii — coś poszło nie tak po stronie KSeF w sposób, którego system nie potrafił dokładniej opisać. Spróbuj powtórzyć operację po chwili; jeśli błąd się powtarza, skontaktuj się z administratorem KSeF w swojej firmie albo z pomocą techniczną, podając dokładny czas próby i — jeśli to możliwe — treść pełnego komunikatu.

Czego w tym spisie nie ma

Ten spis obejmuje kody błędów, które Biurko rozpoznaje i rozróżnia jako osobne, nazwane sytuacje. KSeF może zwrócić także inny kod, którego tu nie ma — API systemu jest szersze niż lista najczęściej spotykanych błędów. Jeśli trafiasz na kod spoza tego zestawienia, sprawdź dokładną treść komunikatu zwróconego przez KSeF — zwykle mówi wprost, czego dotyczy problem — a jeśli to nie wystarczy, skontaktuj się z pomocą techniczną, podając pełny kod i treść błędu.