KSeF komunikaty błędu
Co musisz wiedzieć
Krajowy System e-Faktur (KSeF) jest centralnym systemem administracji skarbowej do wystawiania i otrzymywania faktur ustrukturyzowanych w formacie XML.
Na tej stronie znajdziesz uporządkowane informacje dotyczące tematu: KSeF komunikaty błędu. Opis koncentruje się na aktualnych przepisach oraz komunikatach Ministerstwa Finansów.
Instrukcja krok po kroku
1. Zanotuj kod i treść błędu
Gdy pojawia się błąd, zapisz: pełny kod błędu (np. 21405, 30001), treść komunikatu z pola Details, timestamp wystąpienia, operację, która wywołała błąd. Te informacje są kluczowe do diagnostyki.
2. Sprawdź dokumentację błędów
Odszukaj kod błędu w dokumentacji API KSeF 2.0 dostępnej na stronie MF. Dokumentacja zawiera opisy wszystkich kodów z zalecanymi działaniami naprawczymi.
3. Zidentyfikuj kategorię błędu
Błędy dzielą się na kategorie: 2xxxx – walidacja danych, 3xxxx – duplikaty i konflikty, 25xxx – certyfikaty, 4xxxx – błędy HTTP, 5xxxx – błędy serwera. Kategoria wskazuje kierunek naprawy.
4. Napraw problem
Postępuj zgodnie z zaleceniami dla danego kodu: popraw strukturę danych, odśwież token, sprawdź uprawnienia, poczekaj przy błędach serwera. Po naprawie ponów operację.
5. Zgłoś nieznany błąd
Jeśli komunikat jest niezrozumiały lub nie ma go w dokumentacji, zgłoś problem przez formularz na stronie MF. Dołącz wszystkie zanotowane informacje o błędzie.
Najczęstsze problemy i rozwiązania
Otrzymuję niezrozumiały komunikat błędu
Sprawdź dokumentację API dla danego kodu. Jeśli komunikat jest nadal niejasny, skontaktuj się z pomocą techniczną KSeF przez formularz na stronie MF lub producenta oprogramowania.
Błąd pojawia się mimo poprawnych danych
Sprawdź szczegółowo pole Details w odpowiedzi API – wskazuje konkretny element, który nie przeszedł walidacji. Czasem problem dotyczy formatowania (np. daty, NIP bez myślników).
Gdzie znajdę pełną listę kodów błędów?
Dokumentacja błędów dostępna jest w specyfikacji OpenAPI oraz na stronie ksef.podatki.gov.pl oraz w repozytorium GitHub CIRFMF/ksef-docs. Producenci oprogramowania często mają własne przewodniki.
Kategorie kodów błędów
| Zakres | Kategoria | Opis |
|---|---|---|
| 21xxx | Walidacja | Błędy struktury lub formatu danych |
| 25xxx | Certyfikaty | Problemy z certyfikatami KSeF |
| 30xxx | Duplikaty | Konflikt z istniejącymi danymi |
| 440xx | Biznesowe | Kolizje logiki biznesowej |
| 4xx HTTP | Autoryzacja | Brak uprawnień lub sesji |
| 5xx HTTP | Serwer | Problemy po stronie KSeF |
Najczęstsze kody błędów
21405 – błąd walidacji danych wejściowych (nieprawidłowy payload). 30001 – podmiot lub uprawnienie już istnieje (duplikat). 25008 – certyfikat nie istnieje. 25009 – nie można odwołać certyfikatu. 401 – brak autoryzacji. 403 – brak uprawnień. 500 – błąd serwera.
Struktura komunikatu błędu
Odpowiedź błędu API zawiera: HTTP status code (kod HTTP), exceptionCode (unikalny kod błędu KSeF), exceptionDetailList/Details (szczegółowy opis problemu), timestamp (czas wystąpienia). Pole Details jest kluczowe do zrozumienia przyczyny.
Dokumentacja i wsparcie
Pełna dokumentacja błędów: specyfikacja OpenAPI na ksef.podatki.gov.pl, repozytorium GitHub CIRFMF/ksef-docs, podręcznik integratora. Wsparcie: formularz kontaktowy MF, producent oprogramowania, fora branżowe.
FAQ
Gdzie znajdę listę komunikatów błędów KSeF?
Pełna lista komunikatów błędów KSeF jest dostępna w dokumentacji API na stronie Ministerstwa Finansów oraz w repozytorium GitHub CIRFMF/ksef-docs. Każdy błąd ma indywidualny kod i opis.
Jak interpretować komunikaty błędów z KSeF?
Komunikaty błędów zawierają kod błędu (exceptionCode) i szczegółowy opis problemu w polu Details. Kody 21xxx dotyczą walidacji danych, 25xxx certyfikatów, 30xxx duplikatów, a status HTTP (4xx/5xx) wskazuje ogólną kategorię: brak autoryzacji/uprawnień lub błąd serwera.
Co zrobić, gdy otrzymuję niezrozumiały komunikat błędu?
Sprawdź dokumentację API dla danego kodu błędu. Jeśli komunikat jest nadal niezrozumiały, skontaktuj się z pomocą techniczną KSeF przez formularz na stronie Ministerstwa Finansów.
Czy komunikaty błędów są dostępne w języku polskim?
Tak, komunikaty błędów KSeF są dostępne w języku polskim. Dokumentacja techniczna zawiera opisy kodów błędów wraz z zalecanymi działaniami naprawczymi.
Powiązane tematy
Przydatne serwisy
Status i komunikaty
API i narzędzia
Pierwsza grupa – status systemu KSeF i komunikaty techniczne Ministerstwa Finansów, druga – narzędzia do integracji z KSeF i walidacji faktur.