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 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 unikalny kod i opis.
Jak interpretować komunikaty błędów z KSeF?
Komunikaty błędów zawierają kod błędu i szczegółowy opis problemu. Kody 2xx dotyczą walidacji, 3xx autoryzacji, 4xx nieprawidłowych dokumentów, 5xx błędów systemowych.
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.