Lista kodów statusu zwracanych przez API KSeF 2.0 przy wysyłce faktury, w sesji interaktywnej i wsadowej oraz przy uwierzytelnianiu. Opisy kodów pochodzą z oficjalnej specyfikacji API Ministerstwa Finansów; kolumna „Co zrobić” to nasze wyjaśnienie. Te same numery (np. 415, 440, 450) mają różne znaczenie w zależności od operacji, dlatego tabele są rozdzielone.
Sprawdź fakturę FA(3) przed wysyłką →
Status faktury (wysyłka faktury)
| Kod | Opis (KSeF) | Co zrobić |
|---|---|---|
| 100 | Faktura przyjęta do dalszego przetwarzania | Nic. Status pośredni, sprawdź ponownie za chwilę. |
| 150 | Trwa przetwarzanie | Nic. Odczekaj i odpytaj status ponownie. |
| 200 | Sukces | Faktura ma numer KSeF i jest wystawiona. Możesz pobrać UPO. |
| 405 | Przetwarzanie anulowane z powodu błędu sesji | Faktura nie została przetworzona, bo sesja zakończyła się błędem. Sprawdź status sesji, otwórz nową i wyślij fakturę ponownie. |
| 410 | Nieprawidłowy zakres uprawnień | Uwierzytelniony podmiot nie ma uprawnienia do wystawiania faktur w kontekście tego NIP. Nadaj uprawnienie w KSeF lub wyślij z właściwego kontekstu. |
| 415 | Brak możliwości wysyłania faktury z załącznikiem | Faktury z załącznikiem można wysyłać tylko w sesji wsadowej i tylko po zgłoszeniu tej opcji w e-Urzędzie Skarbowym (wyjątek: korekta techniczna faktury offline). |
| 430 | Błąd weryfikacji pliku faktury | Plik nie przeszedł kontroli technicznej XML: niezgodność ze schematem FA(3) zadeklarowanym przy otwarciu sesji, kodowanie inne niż UTF-8, znak BOM, instrukcje przetwarzania XML lub niezalecane znaki Unicode. Sprawdź plik w walidatorze przed ponowną wysyłką. Sprawdź plik → |
| 435 | Błąd odszyfrowania pliku | KSeF nie odszyfrował faktury. Wymagane: AES-256-CBC (klucz 256 bit, IV 128 bit, PKCS#7), klucz symetryczny zaszyfrowany RSAES-OAEP (SHA-256/MGF1) kluczem publicznym KSeF. Zwykle błąd w module integracji, nie w treści faktury. |
| 440 | Duplikat faktury | W KSeF istnieje już faktura z tą samą kombinacją: NIP sprzedawcy (Podmiot1/NIP), RodzajFaktury i numer faktury (P_2). Unikalność obowiązuje 10 lat. Nadaj nowy numer albo, jeśli to ponowna wysyłka, pobierz numer KSeF oryginału (pola originalKsefNumber, originalSessionReferenceNumber). |
| 450 | Błąd weryfikacji semantyki dokumentu faktury | Faktura jest poprawnym XML, ale treść narusza reguły FA(3): brak wymaganego pola (np. roli Podmiot3), niepoprawny format (NIP, NrVatUE, numer rachunku, SWIFT), sprzeczne adnotacje P_16–P_23, data wystawienia P_1 późniejsza niż data przyjęcia, błędna suma kontrolna NIP. Komunikat KSeF zawiera szczegóły; nasz walidator wskazuje pole przed wysyłką. Sprawdź plik → |
| 500 | Nieznany błąd ({statusCode}) | Błąd po stronie KSeF. Ponów wysyłkę później; jeśli się powtarza, zgłoś do wsparcia KSeF z numerem referencyjnym sesji. |
| 550 | Operacja została anulowana przez system | Przetwarzanie przerwane z przyczyn wewnętrznych KSeF. Spróbuj ponownie. |
Status sesji wsadowej i interaktywnej
| Kod | Opis (KSeF) | Co zrobić |
|---|---|---|
| 100 | Sesja wsadowa rozpoczęta | |
| 150 | Trwa przetwarzanie | |
| 200 | Sesja wsadowa przetworzona pomyślnie | Sprawdź status każdej faktury osobno: sesja może się udać, a pojedyncze faktury mieć 430/440/450. |
| 405 | Błąd weryfikacji poprawności dostarczonych elementów paczki | Niezgodność części paczki z deklaracją przy otwarciu sesji (skróty, rozmiary, liczba części). |
| 415 | Błąd odszyfrowania dostarczonego klucza | Klucz symetryczny zaszyfrowano niewłaściwym kluczem publicznym KSeF lub algorytmem innym niż RSAES-OAEP (SHA-256/MGF1). |
| 420 | Przekroczony limit faktur w sesji | Limit to 10 000 faktur na sesję. Podziel wysyłkę na kilka sesji. |
| 430 | Błąd dekompresji pierwotnego archiwum | Uszkodzony lub niepoprawny plik ZIP. |
| 435 | Błąd odszyfrowania zaszyfrowanych części archiwum | Części ZIP zaszyfrowane niezgodnie z wymaganiami (AES-256-CBC, PKCS#7). |
| 440 | Sesja anulowana (przekroczono czas wysyłki / nie przesłano faktur) | Prześlij części paczki w wymaganym czasie albo nie zamykaj pustej sesji. |
| 445 | Błąd weryfikacji, brak poprawnych faktur | Żadna faktura w sesji nie przeszła weryfikacji. Sprawdź statusy pojedynczych faktur (najczęściej 430 lub 450) i popraw pliki. Sprawdź plik → |
| 500 | Nieznany błąd ({statusCode}) | Ponów później. |
Uwierzytelnianie
| Kod | Opis (KSeF) | Co zrobić |
|---|---|---|
| 415 | Uwierzytelnianie zakończone niepowodzeniem: brak przypisanych uprawnień | Osoba lub certyfikat nie ma uprawnień w kontekście NIP. Nadaj uprawnienia w KSeF. |
| 425 | Uwierzytelnienie unieważnione | Sesja i refresh tokeny zostały unieważnione przez użytkownika. Uwierzytelnij się ponownie. |
| 450 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu | Token KSeF nieprawidłowy, nieaktywny, unieważniony, źle zaszyfrowany lub użyty w innym kontekście niż wydany. Uwaga: to inny kod 450 niż błąd semantyki faktury. |
| 460 | Uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu | Certyfikat nieważny, odwołany, zawieszony lub z niezaufanym łańcuchem. |
| 470 | Uwierzytelnianie zakończone niepowodzeniem | Próba użycia metod autoryzacyjnych osoby zmarłej. |
| 480 | Uwierzytelnienie zablokowane | Podejrzenie incydentu bezpieczeństwa. Kontakt z Ministerstwem Finansów przez formularz zgłoszeniowy. |
Które błędy wykryjesz przed wysyłką
- 430: zgodność ze schematem FA(3), kodowanie UTF-8 bez BOM, niezalecane znaki Unicode. Walidator sprawdza XSD i znaki XML.
- 450: reguły semantyczne FA(3) (adnotacje, role podmiotów, formaty NIP i rachunków, kursy walut). Każdy błąd w walidatorze ma kod i stronę z opisem w katalogu reguł KSeF.
- 440, 410, 415, 435: zależą od stanu KSeF, uprawnień lub modułu integracji; walidator pliku ich nie wykryje.
Najczęstsze pytania
Co oznacza błąd 450 w KSeF?
Przy wysyłce faktury kod 450 to „Błąd weryfikacji semantyki dokumentu faktury”: XML jest poprawny technicznie, ale jego treść narusza reguły FA(3), np. brak wymaganego pola, zły format NIP lub numeru rachunku, sprzeczne adnotacje. Przy logowaniu kod 450 oznacza błędny token KSeF.
Co oznacza błąd 440 w KSeF?
Przy wysyłce faktury: duplikat faktury. KSeF ma już fakturę z tym samym NIP sprzedawcy, rodzajem faktury i numerem (P_2). Przy sesji wsadowej 440 oznacza anulowanie sesji z powodu przekroczenia czasu lub braku faktur.
Jak uniknąć odrzucenia faktury przez KSeF?
Przed wysyłką sprawdź plik XML w walidatorze FA(3): kontrola XSD wychwytuje przyczyny błędu 430, a reguły semantyczne większość przyczyn błędu 450. Duplikatów (440) i uprawnień (410) nie da się sprawdzić bez dostępu do KSeF.
Czy odrzucona faktura jest wystawiona?
Nie. Faktura w KSeF jest wystawiona dopiero po nadaniu numeru KSeF (status 200). Fakturę z błędem trzeba poprawić i wysłać ponownie; nie wystawia się do niej korekty.
Źródło: specyfikacja API KSeF 2.0 i dokumentacja „Weryfikacja faktury” (github.com/CIRFMF/ksef-docs), stan na 15.10.2026.