Kody błędów KSeF po ludzku

    Co znaczy każdy kod błędu i statusu KSeF 2.0, skąd się bierze i jak go naprawić. Brzmienie kodów z dokumentacji Ministerstwa Finansów, odpowiedzi sprawdzone na środowisku testowym KSeF.

    Przykłady:

    Tłumaczymy w Twojej przeglądarce — wklejony tekst nie jest nigdzie wysyłany.

    Najczęstsze błędy KSeF

    450Błąd weryfikacji semantyki faktury / błędny tokenPrzy wysyłce: plik faktury jest niezgodny ze schemą FA(3) albo z regułami KSeF — szczegóły wskazują pole do poprawy. Przy logowaniu: token jest błędny, nieaktywny albo wygenerowany dla innego NIP-u.440Duplikat fakturyPrzy wysyłce: faktura o tym numerze, rodzaju i NIP-ie sprzedawcy już jest w KSeF — nie wysyłaj jej drugi raz, tylko odszukaj numer KSeF z komunikatu. Przy sesji: sesja zamknęła się bez faktur albo minął jej czas — otwórz nową.401Wymagane jest uwierzytelnienie (Unauthorized)KSeF nie rozpoznał tokena dostępu w zapytaniu: brak go, wygasł albo program łączy się ze starym API. Zaloguj się ponownie; jeśli to nie pomaga, wygeneruj nowy token KSeF.415Brak uprawnień / faktura z załącznikiemPrzy logowaniu: osoba lub certyfikat nie ma żadnych uprawnień w tym NIP-ie — trzeba je nadać (ZAW-FA albo w Aplikacji Podatnika). Przy wysyłce: faktury z załącznikiem wymagają zgłoszenia w e-Urzędzie Skarbowym i sesji wsadowej.403Brak wymaganych uprawnień (Forbidden)Logowanie się udało, ale token lub osoba nie ma uprawnienia do tej operacji — np. token tylko do przeglądania faktur użyty do wysyłki. Wygeneruj token z uprawnieniem „wystawianie faktur”.445Błąd weryfikacji, brak poprawnych fakturWszystkie faktury w sesji zostały odrzucone. Sam kod 445 nie mówi dlaczego — przyczyny są w statusach poszczególnych faktur (najczęściej 450 albo 440).410Nieprawidłowy zakres uprawnieńNIP sprzedawcy na fakturze różni się od NIP-u, w którego kontekście jesteś zalogowany, a ten kontekst nie ma uprawnień do wystawiania faktur w imieniu sprzedawcy. Zaloguj się tokenem firmy-sprzedawcy albo nadaj uprawnienie w Aplikacji Podatnika.429Za dużo zapytań (Too Many Requests)Przekroczony limit zapytań do API KSeF. Odczekaj tyle sekund, ile podaje nagłówek Retry-After, i nie ponawiaj w pętli — kolejne przekroczenia wydłużają blokadę.430Błąd weryfikacji pliku fakturyPlik dotarł do KSeF w innej postaci, niż zadeklarował program: ze znakiem BOM na początku albo zmieniony po policzeniu skrótu. Zapisz XML w UTF-8 bez BOM i wyślij ponownie; jeśli błąd wraca, zgłoś go dostawcy programu.21405Błąd walidacji danych wejściowychZapytanie wysłane przez program ma błędne pole: zły format NIP-u, za długi zakres dat, nieobsługiwany formularz. Szczegół w komunikacie wskazuje, które.460Błąd certyfikatu przy logowaniuCertyfikat użyty do logowania (kwalifikowany, pieczęć albo certyfikat KSeF) wygasł, został odwołany albo nie pochodzi od zaufanego wystawcy. Użyj ważnego certyfikatu albo zaloguj się tokenem KSeF.503Usługa niedostępna (Service Unavailable)Serwer KSeF chwilowo nie przyjmuje zapytań — przerwa techniczna, awaria albo przeciążenie. Sprawdź status KSeF; przy ogłoszonej niedostępności możesz wystawić fakturę offline.

    Wszystkie kody KSeF 2.0

    74 kodów: statusy faktur, sesji i logowania, kody wyjątków API i kody HTTP.

    Wysyłka faktury

    440

    Duplikat faktury

    Status faktury w sesji:
    „Duplikat faktury”
    Duplikat faktury. Faktura o numerze KSeF: … została już prawidłowo przesłana do systemu w sesji: …
    Status sesji wysyłki:
    „Sesja anulowana”
    Przekroczono czas wysyłki · Nie przesłano faktur
    Status operacji na uprawnieniach:
    „Operacja niedozwolona dla wskazanych powiązań identyfikatorów”

    Co zrobić: Przy wysyłce: faktura o tym numerze, rodzaju i NIP-ie sprzedawcy już jest w KSeF — nie wysyłaj jej drugi raz, tylko odszukaj numer KSeF z komunikatu. Przy sesji: sesja zamknęła się bez faktur albo minął jej czas — otwórz nową.

    Pełny opis błędu 440
    450

    Błąd weryfikacji semantyki faktury / błędny token

    Status faktury w sesji:
    „Błąd weryfikacji semantyki dokumentu faktury”
    Data wystawienia faktury nie może być późniejsza niż data przyjęcia do systemu. · Nieprawidłowy XML · The 'P_1' element is invalid - The value '11.10.2026' is invalid according to its datatype 'TDataT' - The Pattern constraint failed.
    Status logowania (uwierzytelniania):
    „Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu”
    Nieprawidłowy token. · Token nie może być użyty w kontekście nip-… · Token nieaktywny
    Status operacji na uprawnieniach:
    „Operacja niedozwolona dla wskazanego identyfikatora lub jego typu”

    Co zrobić: Przy wysyłce: plik faktury jest niezgodny ze schemą FA(3) albo z regułami KSeF — szczegóły wskazują pole do poprawy. Przy logowaniu: token jest błędny, nieaktywny albo wygenerowany dla innego NIP-u.

    Pełny opis błędu 450
    430

    Błąd weryfikacji pliku faktury

    Status faktury w sesji:
    „Błąd weryfikacji pliku faktury”
    Wykryto BOM w pliku. · Skrót SHA-256 faktury nie jest zgodny z zadeklarowaną wartością: '…'. · Rozmiar faktury nie zgadza się z zadeklarowaną wartością: '…'.
    Status sesji wysyłki:
    „Błąd dekompresji pierwotnego archiwum”
    Status operacji na uprawnieniach:
    „Kontekst identyfikatora nie odpowiada wymaganej roli lub uprawnieniom”

    Co zrobić: Plik dotarł do KSeF w innej postaci, niż zadeklarował program: ze znakiem BOM na początku albo zmieniony po policzeniu skrótu. Zapisz XML w UTF-8 bez BOM i wyślij ponownie; jeśli błąd wraca, zgłoś go dostawcy programu.

    Pełny opis błędu 430
    410

    Nieprawidłowy zakres uprawnień

    Status faktury w sesji:
    „Nieprawidłowy zakres uprawnień”
    Kontekst 9138880104 nie jest uprawniony do wystawienia faktury w imieniu sprzedawcy (NIP: 9231147966)
    Status operacji na uprawnieniach:
    „Podane identyfikatory są niezgodne lub pozostają w niewłaściwej relacji”

    Co zrobić: NIP sprzedawcy na fakturze różni się od NIP-u, w którego kontekście jesteś zalogowany, a ten kontekst nie ma uprawnień do wystawiania faktur w imieniu sprzedawcy. Zaloguj się tokenem firmy-sprzedawcy albo nadaj uprawnienie w Aplikacji Podatnika.

    Pełny opis błędu 410
    415

    Brak uprawnień / faktura z załącznikiem

    Status logowania (uwierzytelniania):
    „Uwierzytelnianie zakończone niepowodzeniem”
    Brak przypisanych uprawnień
    Status faktury w sesji:
    „Brak możliwości wysyłania faktury z załącznikiem”
    Status eksportu (pobierania paczki faktur):
    „Błąd odszyfrowania dostarczonego klucza”

    Co zrobić: Przy logowaniu: osoba lub certyfikat nie ma żadnych uprawnień w tym NIP-ie — trzeba je nadać (ZAW-FA albo w Aplikacji Podatnika). Przy wysyłce: faktury z załącznikiem wymagają zgłoszenia w e-Urzędzie Skarbowym i sesji wsadowej.

    Pełny opis błędu 415
    435

    Błąd odszyfrowania pliku

    Status faktury w sesji:
    „Błąd odszyfrowania pliku”
    Status sesji wysyłki:
    „Błąd odszyfrowania zaszyfrowanych części archiwum”

    Co zrobić: KSeF nie odszyfrował faktury kluczem podanym przy otwarciu sesji (AES-256-CBC, klucz zaszyfrowany kluczem publicznym MF). To błąd programu wysyłającego — zgłoś go dostawcy; zwykle pomaga otwarcie nowej sesji.

    405

    Przetwarzanie anulowane z powodu błędu sesji

    Status faktury w sesji:
    „Przetwarzanie anulowane z powodu błędu sesji”
    Status sesji wysyłki:
    „Błąd weryfikacji poprawności dostarczonych elementów paczki”

    Co zrobić: Faktura nie została sprawdzona, bo cała sesja (paczka) była błędna. Faktura nie ma numeru KSeF — wyślij ją ponownie w nowej sesji.

    21166

    Korekta techniczna niedostępna

    Wysłanie faktury:
    „Korekta techniczna niedostępna.”
    Faktura posiada już przetworzoną prawidłowo korektę techniczną.

    Co zrobić: Ta faktura offline ma już przyjętą korektę techniczną — drugiej nie wyślesz.

    21167

    Status faktury nie pozwala na korektę techniczną

    Wysłanie faktury:
    „Status faktury nie pozwala na korektę techniczną.”
    Nie można wysłać korekty technicznej do prawidłowo przetworzonej faktury.

    Co zrobić: Korektę techniczną wysyła się tylko do faktury offline, którą KSeF odrzucił. Przyjętą fakturę poprawia się zwykłą fakturą korygującą.

    21402

    Nieprawidłowy rozmiar pliku

    Wysłanie faktury:
    „Nieprawidłowy rozmiar pliku.”
    Długość treści nie zgadza się z rozmiarem pliku.

    Co zrobić: Program zadeklarował inny rozmiar pliku niż wysłał. Błąd po stronie programu — zgłoś go dostawcy.

    21403

    Nieprawidłowy skrót pliku

    Wysłanie faktury:
    „Nieprawidłowy skrót pliku.”
    Skrót treści nie zgadza się ze skrótem pliku.

    Co zrobić: Skrót SHA-256 wysłanej treści różni się od zadeklarowanego. Błąd po stronie programu — zgłoś go dostawcy.

    Sesja wysyłki

    420

    Przekroczony limit / brak uprawnień do operacji

    Status sesji wysyłki:
    „Przekroczony limit faktur w sesji”
    Status eksportu (pobierania paczki faktur):
    „Zakres filtrowania wykracza poza dostępny zakres danych”
    Parametr dateRange.from jest późniejszy niż PermanentStorageHwmDate przy włączonym restrictToPermanentStorageHwmDate.
    Status operacji na uprawnieniach:
    „Użyte poświadczenia nie mają uprawnień do wykonania tej operacji”

    Co zrobić: W jednej sesji można wysłać najwyżej 10 000 faktur — podziel paczkę na kilka sesji. Przy pobieraniu: zakres dat sięga poza dane już utrwalone w KSeF — skróć go albo spróbuj później.

    21155

    Przekroczono dozwoloną liczbę faktur w sesji

    Wysłanie faktury:
    „Przekroczono dozwoloną liczbę faktur w sesji.”
    Sesja o numerze referencyjnym … osiągnęła dozwolony limit liczby faktur …

    Co zrobić: Zamknij sesję i wyślij pozostałe faktury w nowej. Limit to 10 000 faktur na sesję.

    21173

    Brak sesji o wskazanym numerze

    Status sesji, wysyłka, UPO:
    „Brak sesji o wskazanym numerze referencyjnym.”

    Co zrobić: Numer sesji jest błędny albo dotyczy innego NIP-u lub innego środowiska (testowe/produkcyjne).

    21178

    Nie znaleziono UPO

    Pobranie UPO:
    „Nie znaleziono UPO dla podanych kryteriów.”

    Co zrobić: UPO powstaje dopiero dla faktury przyjętej przez KSeF. Sprawdź status faktury; jeśli jest przyjęta, pobierz UPO ponownie za chwilę.

    21180

    Status sesji nie pozwala na wykonanie operacji

    Wysłanie faktury, zamknięcie sesji:
    „Status sesji nie pozwala na wykonanie operacji.”
    Status sesji … uniemożliwia wysyłkę faktur.

    Co zrobić: Sesja jest już zamknięta albo anulowana. Otwórz nową sesję i wyślij w niej faktury.

    21184

    Sesja tymczasowo niedostępna

    Wysłanie faktury:
    „Sesja tymczasowo niedostępna.”
    Trwają prace serwisowe i sesja … jest tymczasowo niedostępna. Spróbuj ponownie później lub otwórz nową sesję, aby wysłać kolejne faktury.

    Co zrobić: Trwają prace serwisowe po stronie KSeF. Otwórz nową sesję albo spróbuj później; sprawdź też, czy KSeF działa.

    21157

    Nieprawidłowy rozmiar części pakietu

    Sesja wsadowa:
    „Nieprawidłowy rozmiar części pakietu.”

    Co zrobić: Zadeklarowany rozmiar części paczki nie zgadza się z wysłanym plikiem — błąd programu wysyłającego paczki.

    21161

    Przekroczono dozwoloną liczbę części pakietu

    Sesja wsadowa:
    „Przekroczono dozwoloną liczbę części pakietu.”

    Co zrobić: Paczka może mieć najwyżej 50 części (po 100 MB). Podziel wysyłkę na kilka sesji.

    21205

    Pakiet nie może być pusty

    Zamknięcie sesji wsadowej:
    „Pakiet nie może być pusty.”
    Nie przesłano zadeklarowanej '…' części pliku.

    Co zrobić: Przed zamknięciem sesji wsadowej nie wysłano wszystkich zadeklarowanych części paczki. Wyślij paczkę ponownie.

    21208

    Przekroczony czas wysyłki

    Zamknięcie sesji wsadowej:
    „Czas oczekiwania na requesty upload lub finish został przekroczony.”
    Sesja anulowana, przekroczony czas wysyłki.

    Co zrobić: Paczka wysyłała się zbyt długo i sesja została anulowana. Wyślij ją ponownie, najlepiej mniejszymi częściami.

    Logowanie i token

    460

    Błąd certyfikatu przy logowaniu

    Status logowania (uwierzytelniania):
    „Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu”
    Nieważny certyfikat · Błąd weryfikacji łańcucha certyfikatów · Niezaufany łańcuch certyfikatów

    Co zrobić: Certyfikat użyty do logowania (kwalifikowany, pieczęć albo certyfikat KSeF) wygasł, został odwołany albo nie pochodzi od zaufanego wystawcy. Użyj ważnego certyfikatu albo zaloguj się tokenem KSeF.

    Pełny opis błędu 460
    425

    Uwierzytelnienie unieważnione

    Status logowania (uwierzytelniania):
    „Uwierzytelnienie unieważnione”
    Uwierzytelnienie i powiązane refresh tokeny zostały unieważnione przez użytkownika

    Co zrobić: Ta sesja logowania została zakończona (np. ktoś unieważnił ją w Aplikacji Podatnika). Zaloguj się ponownie.

    470

    Metody autoryzacyjne osoby zmarłej

    Status logowania (uwierzytelniania):
    „Uwierzytelnianie zakończone niepowodzeniem”
    Próba wykorzystania metod autoryzacyjnych osoby zmarłej

    Co zrobić: Dane logowania należą do osoby zmarłej i nie można ich już używać. Faktury firmy w spadku wystawia osoba z własnymi uprawnieniami, np. zarządca sukcesyjny.

    480

    Uwierzytelnienie zablokowane

    Status logowania (uwierzytelniania):
    „Uwierzytelnienie zablokowane”
    Podejrzenie incydentu bezpieczeństwa. Skontaktuj się z Ministerstwem Finansów przez formularz zgłoszeniowy.

    Co zrobić: KSeF zablokował logowanie z powodu podejrzenia incydentu bezpieczeństwa. Skontaktuj się z MF przez formularz zgłoszeniowy KSeF.

    21111

    Nieprawidłowe wyzwanie autoryzacyjne

    Logowanie tokenem lub podpisem:
    „Nieprawidłowe wyzwanie autoryzacyjne.”

    Co zrobić: Program użył wyzwania (challenge), które wygasło albo zostało już wykorzystane. Spróbuj zalogować się ponownie; sprawdź też, czy zegar komputera jest ustawiony poprawnie.

    21301

    Brak autoryzacji

    Pobranie lub odświeżenie tokena dostępowego:
    „Brak autoryzacji.”
    Token KSeF został unieważniony. · Tokeny dla operacji uwierzytelniania … zostały już pobrane.

    Co zrobić: Najczęściej token KSeF został unieważniony w Aplikacji Podatnika. Wygeneruj nowy i wklej go w programie.

    21304

    Brak uwierzytelnienia

    Status logowania, tokeny dostępowe:
    „Brak uwierzytelnienia.”
    Operacja uwierzytelniania o numerze referencyjnym … nie została znaleziona.

    Co zrobić: Operacja logowania wygasła albo dotyczy innego środowiska. Zaloguj się od nowa.

    21308

    Metody autoryzacyjne osoby zmarłej

    Tokeny dostępowe:
    „Próba wykorzystania metod autoryzacyjnych osoby zmarłej.”

    Co zrobić: Jak przy statusie 470: logowanie danymi zmarłego nie jest możliwe — potrzebna jest osoba z własnymi uprawnieniami, np. zarządca sukcesyjny.

    21470

    Nieznany identyfikator klucza

    Logowanie tokenem, otwarcie sesji, eksport:
    „Przesłany identyfikator klucza jest nieznany lub wskazuje na wycofany klucz.”
    Klucz o identyfikatorze … nie jest wspierany.

    Co zrobić: Program szyfruje dane wycofanym kluczem publicznym MF. Zaktualizuj program — dostawca musi pobierać aktualne klucze z KSeF.

    9101

    Nieprawidłowy dokument (podpis XAdES)

    Logowanie podpisem XAdES:
    „Nieprawidłowy dokument.”

    Co zrobić: Podpisany plik logowania jest uszkodzony albo nie jest żądaniem uwierzytelnienia KSeF. Pobierz plik do podpisu jeszcze raz.

    9102

    Brak podpisu

    Logowanie podpisem XAdES:
    „Brak podpisu.”

    Co zrobić: Plik nie został podpisany. Podpisz go profilem zaufanym, podpisem kwalifikowanym albo pieczęcią w formacie XAdES.

    9103

    Przekroczona liczba podpisów

    Logowanie podpisem XAdES:
    „Przekroczona liczba dozwolonych podpisów.”

    Co zrobić: Plik logowania może mieć jeden podpis. Podpisz świeżo pobrany plik tylko raz.

    9105

    Nieprawidłowy podpis

    Logowanie podpisem XAdES:
    „Nieprawidłowy podpis.”

    Co zrobić: Podpis nie przeszedł weryfikacji — plik zmieniono po podpisaniu albo podpis ma zły format (wymagany XAdES). Podpisz plik ponownie, bez edytowania go.

    21001

    Nieczytelna treść

    Logowanie podpisem XAdES:
    „Nieczytelna treść.”

    Co zrobić: KSeF nie odczytał podpisanego pliku (zły format albo kodowanie). Zapisz plik jako XML w UTF-8 i podpisz ponownie.

    21115

    Nieprawidłowy certyfikat

    Logowanie podpisem XAdES:
    „Nieprawidłowy certyfikat.”

    Co zrobić: Certyfikat podpisu nie nadaje się do logowania (np. certyfikat KSeF typu „Offline” służy wyłącznie do faktur offline i kodu QR II, nie do logowania). Użyj certyfikatu typu „Authentication” albo innego sposobu logowania.

    21117

    Nieprawidłowy identyfikator podmiotu

    Logowanie podpisem XAdES:
    „Nieprawidłowy identyfikator podmiotu dla wskazanego typu kontekstu.”

    Co zrobić: Identyfikator w żądaniu logowania nie pasuje do typu kontekstu (np. NIP podany jako identyfikator wewnętrzny). Sprawdź NIP i typ kontekstu.

    21217

    Nieprawidłowe kodowanie znaków

    Logowanie podpisem XAdES:
    „Nieprawidłowe kodowanie znaków.”

    Co zrobić: Plik nie jest zapisany w UTF-8. Zapisz go w UTF-8 i podpisz ponownie.

    21401

    Dokument niezgodny ze schemą (XSD)

    Logowanie podpisem XAdES:
    „Dokument nie jest zgodny ze schemą (xsd).”

    Co zrobić: Podpisane żądanie logowania ma niepoprawną strukturę — błąd programu, który je przygotował. Uwaga: błędy struktury faktury KSeF zwraca jako status 450, nie 21401.

    21406

    Konflikt podpisu i typu uwierzytelnienia

    Logowanie podpisem XAdES:
    „Konflikt podpisu i typu uwierzytelnienia.”

    Co zrobić: Rodzaj podpisu nie pasuje do wybranego sposobu identyfikacji (np. odcisk certyfikatu przy podpisie profilem zaufanym). Wybierz zgodny typ logowania.

    Uprawnienia

    26001

    Nie można nadać tokenowi uprawnień, których nie masz

    Generowanie tokena:
    „Nie można nadać tokenowi uprawnień których nie posiadasz.”

    Co zrobić: Token może mieć tylko uprawnienia, które ma osoba go generująca. Poproś właściciela firmy o nadanie uprawnień albo o wygenerowanie tokena.

    26002

    Nie można wygenerować tokena w tym kontekście

    Generowanie tokena:
    „Nie można wygenerować tokena dla obecnego typu kontekstu.”

    Co zrobić: W tym kontekście logowania tokenów nie generuje się. Zaloguj się w kontekście NIP-u firmy.

    Pobieranie i wyszukiwanie faktur

    21405

    Błąd walidacji danych wejściowych

    Prawie każde zapytanie do API (HTTP 400):
    „Błąd walidacji danych wejściowych.”
    Invalid NIP format. · 'dateRange' must not exceed 100 days. · Wskazany kod formularza nie jest wspierany.

    Co zrobić: Zapytanie wysłane przez program ma błędne pole: zły format NIP-u, za długi zakres dat, nieobsługiwany formularz. Szczegół w komunikacie wskazuje, które.

    Pełny opis błędu 21405
    21164

    Faktura o podanym numerze nie istnieje

    Pobranie faktury po numerze KSeF:
    „Faktura o podanym identyfikatorze nie istnieje.”
    Faktura o numerze KSeF … nie została znaleziona.

    Co zrobić: Sprawdź numer KSeF (literówka, inne środowisko) i czy jesteś zalogowany w kontekście sprzedawcy albo nabywcy tej faktury.

    21165

    Faktura nie jest jeszcze dostępna

    Pobranie faktury po numerze KSeF:
    „Faktura o podanym numerze KSeF nie jest jeszcze dostępna.”
    Faktura … została przetworzona, ale nie jest jeszcze dostępna do pobrania. Spróbuj ponownie później.

    Co zrobić: Faktura ma już numer KSeF, ale trwa jej zapisywanie. Spróbuj za kilka minut.

    21175

    Wynik zapytania nie istnieje

    Status eksportu paczki faktur:
    „Wynik zapytania o podanym identyfikatorze nie istnieje.”

    Co zrobić: Eksport o tym numerze nie istnieje albo wygasł. Zleć pobranie paczki od nowa.

    21181

    Nieprawidłowe żądanie eksportu faktur

    Eksport paczki faktur:
    „Nieprawidłowe żądanie eksportu faktur.”

    Co zrobić: W tym kontekście logowania nie można pobrać faktur wskazanego typu (sprzedaż, zakupy, podmiot trzeci). Zmień typ podmiotu albo zaloguj się w innym kontekście.

    21182

    Limit trwających eksportów

    Eksport paczki faktur:
    „Osiągnięto limit trwających eksportów.”

    Co zrobić: Trwa już zbyt wiele pobrań paczek naraz. Poczekaj, aż się zakończą, i spróbuj ponownie.

    21183

    Zakres dat poza dostępnymi danymi

    Lista faktur:
    „Zakres filtrowania wykracza poza dostępny zakres danych.”

    Co zrobić: Początek zakresu jest późniejszy niż moment, do którego KSeF ma już trwale zapisane faktury. Spróbuj później albo przesuń zakres.

    21418

    Nieprawidłowy token kontynuacji

    Listy (sesje, faktury, tokeny):
    „Przekazany token kontynuacji ma nieprawidłowy format.”

    Co zrobić: Program pyta o kolejną stronę wyników nieważnym znacznikiem. Pobierz listę od początku.

    210

    Eksport wygasł

    Status eksportu (pobierania paczki faktur):
    „Eksport faktur wygasł i nie jest już dostępny do pobrania”

    Co zrobić: Paczka z pobranymi fakturami jest dostępna tylko przez ograniczony czas. Zleć pobranie od nowa.

    Kody HTTP

    401

    Wymagane jest uwierzytelnienie (Unauthorized)

    Odpowiedź HTTP API KSeF:
    „Unauthorized — „Wymagane jest uwierzytelnienie.””

    Co zrobić: KSeF nie rozpoznał tokena dostępu w zapytaniu: brak go, wygasł albo program łączy się ze starym API. Zaloguj się ponownie; jeśli to nie pomaga, wygeneruj nowy token KSeF.

    Pełny poradnik
    403

    Brak wymaganych uprawnień (Forbidden)

    Odpowiedź HTTP API KSeF:
    „Forbidden — „Brak wymaganych uprawnień do wykonania operacji w bieżącym kontekście.””

    Co zrobić: Logowanie się udało, ale token lub osoba nie ma uprawnienia do tej operacji — np. token tylko do przeglądania faktur użyty do wysyłki. Wygeneruj token z uprawnieniem „wystawianie faktur”.

    Pełny opis błędu 403
    400

    Żądanie nieprawidłowe / operacja nieudana

    Odpowiedź HTTP API KSeF:
    „Bad Request — „Żądanie jest nieprawidłowe.””
    Szczegóły są w polu errors: kod wyjątku (np. 21405) i opis.
    Status operacji na uprawnieniach:
    „Operacja zakończona niepowodzeniem”
    Status wniosku o certyfikat KSeF:
    „Wniosek odrzucony”
    Osiągnięto dopuszczalny limit posiadanych certyfikatów. · Klucz publiczny został już certyfikowany przez inny podmiot.

    Co zrobić: Sam kod 400 nic nie mówi — ważny jest kod wyjątku w treści odpowiedzi (najczęściej 21405 z opisem błędnego pola).

    429

    Za dużo zapytań (Too Many Requests)

    Odpowiedź HTTP API KSeF:
    „Too Many Requests”
    Przekroczono limit 20 żądań na minutę. Spróbuj ponownie po 30 sekundach.

    Co zrobić: Przekroczony limit zapytań do API KSeF. Odczekaj tyle sekund, ile podaje nagłówek Retry-After, i nie ponawiaj w pętli — kolejne przekroczenia wydłużają blokadę.

    Pełny opis błędu 429
    500

    Nieznany błąd

    Status faktury w sesji:
    „Nieznany błąd ({statusCode})”
    Status logowania (uwierzytelniania):
    „Nieznany błąd”
    Status eksportu (pobierania paczki faktur):
    „Nieznany błąd ({statusCode})”

    Co zrobić: Błąd po stronie KSeF bez bliższego opisu. Sprawdź, czy KSeF działa, i spróbuj ponownie; faktura z tym statusem nie ma numeru KSeF.

    550

    Operacja anulowana przez system

    Status faktury w sesji:
    „Operacja została anulowana przez system”
    Przetwarzanie zostało przerwane z przyczyn wewnętrznych systemu. Spróbuj ponownie
    Status logowania (uwierzytelniania):
    „Operacja została anulowana przez system”
    Status operacji na uprawnieniach:
    „Operacja została anulowana przez system”

    Co zrobić: KSeF przerwał przetwarzanie z własnych przyczyn. Faktura nie ma numeru KSeF — wyślij ją ponownie (nie będzie duplikatem).

    Certyfikaty KSeF

    25001

    Brak danych do CSR

    Wniosek o certyfikat KSeF:
    „Brak możliwości pobrania danych do CSR dla wykorzystanego sposobu uwierzytelnienia.”

    Co zrobić: Przy tym sposobie logowania (np. tokenem) nie złożysz wniosku o certyfikat. Zaloguj się podpisem kwalifikowanym, pieczęcią albo profilem zaufanym.

    25002

    Nie można złożyć wniosku certyfikacyjnego

    Wniosek o certyfikat KSeF:
    „Brak możliwości złożenia wniosku certyfikacyjnego dla wykorzystanego sposobu uwierzytelnienia.”

    Co zrobić: Jak przy 25001 — wniosek składa się po zalogowaniu podpisem, pieczęcią albo profilem zaufanym.

    25003

    Dane w CSR niezgodne z logowaniem

    Wniosek o certyfikat KSeF:
    „Dane w CSR nie zgadzają się z danymi w użytym wektorze uwierzytelniającym.”

    Co zrobić: Dane we wniosku (np. NIP, imię i nazwisko) muszą być dokładnie takie, jak zwrócił KSeF w danych do wniosku.

    25004

    Niepoprawny CSR

    Wniosek o certyfikat KSeF:
    „Niepoprawny format CSR lub niepoprawny podpis CSR.”

    Co zrobić: Wygeneruj wniosek CSR ponownie — zły format albo podpis.

    25005

    Wniosek certyfikacyjny nie istnieje

    Status wniosku o certyfikat:
    „Wniosek certyfikacyjny o podanym numerze referencyjnym nie istnieje.”

    Co zrobić: Sprawdź numer referencyjny wniosku i środowisko.

    25006

    Limit wniosków certyfikacyjnych

    Wniosek o certyfikat KSeF:
    „Osiągnięto limit możliwych do złożenia wniosków certyfikacyjnych.”

    Co zrobić: Złożono zbyt wiele wniosków. Odczekaj albo wykorzystaj już wydany certyfikat.

    25007

    Limit posiadanych certyfikatów

    Wniosek o certyfikat KSeF:
    „Osiągnięto limit dopuszczalnej liczby posiadanych certyfikatów.”

    Co zrobić: Unieważnij nieużywane certyfikaty KSeF, zanim złożysz nowy wniosek.

    25008

    Certyfikat nie istnieje

    Unieważnienie certyfikatu:
    „Certyfikat o podanym numerze seryjnym nie istnieje.”

    Co zrobić: Sprawdź numer seryjny certyfikatu.

    25009

    Certyfikatu nie można odwołać

    Unieważnienie certyfikatu:
    „Nie można odwołać wskazanego certyfikatu, ponieważ jest już odwołany, zablokowany lub nieważny.”

    Co zrobić: Ten certyfikat już nie działa — nie trzeba nic robić.

    25010

    Nieprawidłowy typ lub długość klucza

    Wniosek o certyfikat KSeF:
    „Nieprawidłowy typ lub długość klucza.”

    Co zrobić: Wygeneruj klucz obsługiwany przez KSeF (RSA 2048 bitów albo EC P-256) i złóż wniosek ponownie.

    25011

    Nieprawidłowy algorytm podpisu CSR

    Wniosek o certyfikat KSeF:
    „Nieprawidłowy algorytm podpisu CSR.”

    Co zrobić: Podpisz wniosek dozwolonym algorytmem: RSA PKCS#1 v1.5, RSA-PSS albo ECDSA.

    Statusy, które nie są błędem

    100

    Przyjęto do przetwarzania

    Status faktury w sesji:
    „Faktura przyjęta do dalszego przetwarzania”
    Status sesji wysyłki:
    „Sesja interaktywna otwarta / Sesja wsadowa rozpoczęta”
    Status logowania (uwierzytelniania):
    „Uwierzytelnianie w toku”

    Co zrobić: To nie błąd. KSeF przyjął plik albo żądanie i jeszcze je sprawdza — status zmieni się sam.

    150

    Trwa przetwarzanie

    Status faktury w sesji, status sesji wysyłki:
    „Trwa przetwarzanie”

    Co zrobić: To nie błąd. Faktura czeka na weryfikację; zwykle trwa to kilka sekund. Nie wysyłaj jej drugi raz.

    170

    Sesja interaktywna zamknięta

    Status sesji wysyłki:
    „Sesja interaktywna zamknięta”

    Co zrobić: To nie błąd. Sesja jest zamknięta i KSeF kończy jej przetwarzanie; potem pojawi się status 200 i zbiorcze UPO.

    200

    Sukces

    Status faktury w sesji:
    „Sukces”
    Status sesji wysyłki:
    „Sesja interaktywna przetworzona pomyślnie”
    Status logowania (uwierzytelniania):
    „Uwierzytelnianie zakończone sukcesem”

    Co zrobić: To nie błąd. Faktura ma numer KSeF i UPO — jest wystawiona.

    Jak czytać komunikat z KSeF

    Odpowiedź KSeF ma zwykle trzy warstwy. Program pokazuje czasem tylko jedną — dlatego ten sam problem bywa opisany jako „błąd 400”, „21405” albo „Invalid NIP format”.

    Kod HTTP 400, 401, 403, 429, 503

    Co stało się z zapytaniem do serwera. 401 — brak logowania, 403 — brak uprawnień, 429 — za dużo zapytań, 503 — serwer niedostępny.

    Status KSeF 100–550

    Stan faktury, sesji, logowania albo eksportu: 100 przyjęto, 150 trwa, 200 sukces, od 400 w górę — odrzucenie z opisem i szczegółami.

    Kod wyjątku 9101–71005

    Dokładny powód odrzucenia zapytania, np. 21405 błąd walidacji danych, 21180 zły status sesji. Pojawia się w treści odpowiedzi HTTP 400.

    Pytania o błędy KSeF

    Czy KSeF teraz działa? Wyślij fakturę i zobacz dokładny powód odrzucenia Jak wygenerować token KSeF

    Gdzie znaleźć kod błędu KSeF?

    Program do faktur pokazuje go w historii wysyłki albo komunikacji z KSeF: jako „status 450”, „kod 440”, „błąd 21405” albo w treści odpowiedzi (pole code). W Aplikacji Podatnika odrzucone faktury mają status z opisem. Wklej cały komunikat do tłumacza na tej stronie — wyciągnie z niego kod i nazwy pól.

    Dlaczego ten sam numer błędu znaczy różne rzeczy?

    KSeF używa tych samych numerów w kilku miejscach: w statusie faktury, statusie sesji, statusie logowania i operacji na uprawnieniach. Na przykład 440 to „Duplikat faktury” przy fakturze, ale „Sesja anulowana” przy sesji. Dlatego przy każdym kodzie podajemy, gdzie się pojawia.

    Czy faktura odrzucona przez KSeF jest wystawiona?

    Nie. Faktura jest wystawiona dopiero wtedy, gdy KSeF nada jej numer KSeF (status 200). Odrzuconą fakturę poprawiasz i wysyłasz ponownie z tym samym numerem — nie będzie duplikatem, bo KSeF pamięta tylko faktury przyjęte.

    Czym różnią się kody HTTP od kodów KSeF?

    Kody HTTP (400, 401, 403, 429, 503) mówią, co stało się z samym zapytaniem do serwera. Kody statusów KSeF (100–550) opisują stan faktury, sesji albo logowania, a kody wyjątków (np. 21405, 21180) — konkretny powód odrzucenia zapytania. Przy błędzie 400 najważniejszy jest kod wyjątku w treści odpowiedzi.

    Skąd pochodzą opisy błędów?

    Brzmienie kodów pochodzi z dokumentacji API KSeF 2.0 Ministerstwa Finansów. Przykładowe odpowiedzi wywołaliśmy sami na środowisku testowym MF, na fikcyjnych firmach testowych. Objaśnienia i porady są nasze — w razie sporu rozstrzyga dokumentacja MF.

    Źródło brzmienia kodów: dokumentacja API KSeF 2.0 Ministerstwa Finansów (github.com/CIRFMF/ksef-api), stan na 11 października 2026 r. Przykłady odpowiedzi: środowisko testowe KSeF, fikcyjne firmy testowe.