KSeF API błędy i obsługa wyjątków
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 API błędy i obsługa wyjątków. Opis koncentruje się na aktualnych przepisach oraz komunikatach Ministerstwa Finansów.
Instrukcja krok po kroku
1. Zidentyfikuj kod błędu
API KSeF zwraca kod błędu w odpowiedzi HTTP i w treści JSON. Zanotuj kod statusu HTTP (401, 403, 500 itd.) oraz szczegółowy kod błędu z pola exceptionCode (np. 21405, 30001, 440xx).
2. Sprawdź opis błędu
W odpowiedzi API znajdziesz pole Details z opisem przyczyny błędu. Przeczytaj komunikat, aby zrozumieć, co wymaga poprawki. Dokumentacja OpenAPI zawiera pełną listę kodów i ich znaczeń.
3. Zdiagnozuj przyczynę
Najczęstsze przyczyny: 401/403 – problemy z autoryzacją lub uprawnieniami; 21405 – błąd walidacji payloadu; 30001 – duplikat; 440xx – kolizje biznesowe; 500 – problem serwera.
4. Napraw problem i ponów żądanie
Popraw dane zgodnie z komunikatem błędu. W przypadku błędów autoryzacji – odśwież token. Przy błędach walidacji – popraw strukturę XML. Przy błędach 500 – poczekaj i ponów próbę.
5. Zaimplementuj obsługę błędów w kodzie
W swoim kodzie zaimplementuj: retry z backoffem dla błędów przejściowych (500), logowanie błędów dla diagnostyki, obsługę specyficznych kodów błędów zgodnie z logiką biznesową.
Najczęstsze problemy i rozwiązania
Otrzymuję błąd 201 – walidacja XSD
Struktura XML faktury jest niezgodna ze schematem XSD. Sprawdź, czy używasz aktualnego schematu (FA2 lub FA3), czy wszystkie wymagane pola są wypełnione i mają prawidłowy format.
Błąd 301 – problem z autoryzacją
Sprawdź ważność tokenu JWT, uprawnienia użytkownika i poprawność certyfikatu. Upewnij się, że token nie wygasł i że masz odpowiednie uprawnienia do wykonania operacji.
Błąd 500 – serwer nie odpowiada
Błąd 500 oznacza problem po stronie serwera KSeF. Poczekaj kilka minut i spróbuj ponownie. Sprawdź status systemu na ksef.podatki.gov.pl. W przypadku dłuższej awarii skorzystaj z trybu offline.
Kody błędów HTTP
| Kod HTTP | Znaczenie | Działanie |
|---|---|---|
| 400 | Błędne żądanie | Sprawdź strukturę payloadu |
| 401 | Nieautoryzowany | Odśwież token JWT |
| 403 | Brak uprawnień | Sprawdź uprawnienia użytkownika |
| 404 | Nie znaleziono | Sprawdź poprawność URL |
| 500 | Błąd serwera | Poczekaj i ponów próbę |
Kody błędów biznesowych KSeF
| Kod | Opis |
|---|---|
| 21405 | Błąd walidacji danych wejściowych |
| 30001 | Podmiot lub uprawnienie już istnieje |
| 25008 | Certyfikat nie istnieje |
| 25009 | Nie można odwołać certyfikatu |
| 440xx | Duplikaty/kolizje biznesowe |
Obsługa błędów przejściowych
Błędy 500 i niektóre błędy sieciowe są przejściowe. Zaimplementuj strategię retry z wykładniczym backoffem: pierwsza próba po 1s, kolejne po 2s, 4s, 8s… Ogranicz liczbę prób do 3-5. Dla błędów 400/401/403 nie ponawiaj – wymagają naprawy danych.
Logowanie i diagnostyka
Loguj wszystkie błędy API z: timestampem, kodem błędu, treścią odpowiedzi, identyfikatorem żądania (jeśli dostępny). Logi pomogą w diagnostyce problemów i zgłaszaniu ich do Ministerstwa Finansów.
FAQ
Jakie są najczęstsze kody błędów w API KSeF?
Najczęstsze kody błędów to: 201 – błąd walidacji XSD, 301 – błąd autoryzacyjny, 401 – nieprawidłowy dokument (np. zduplikowana faktura), 500 – błąd systemowy serwera KSeF. Szczegółowa specyfikacja dostępna jest w dokumentacji API.
Gdzie znajdę oficjalną dokumentację kodów błędów KSeF?
Szczegółowa specyfikacja błędów dostępna jest w dokumentacji API KSeF 2.0 na stronie Ministerstwa Finansów oraz w repozytorium GitHub (CIRFMF/ksef-docs), gdzie znajdują się przewodniki dla integratorów i przykłady kodu.
Co zrobić, gdy otrzymam błąd autoryzacyjny w API KSeF?
Błąd autoryzacyjny najczęściej wynika z nieprawidłowego tokenu, braku uprawnień lub niepoprawnego certyfikatu. Sprawdź ważność tokenu, uprawnienia użytkownika oraz poprawność certyfikatu. Jeśli problem się powtarza, skontaktuj się z Ministerstwem Finansów.
Jak obsługiwać błędy walidacji struktury XML?
Błędy walidacji struktury wynikają z niezgodności ze schematem XSD. Sprawdź, czy faktura zawiera wszystkie wymagane pola, czy format dat jest poprawny i czy struktura jest zgodna z aktualnym schematem FA(2) lub FA(3).