Kody błędów KSeF to informacje zwracane przez API Krajowego Systemu e-Faktur, które wskazują przyczynę nieprawidłowego żądania lub problemu podczas wykonywania operacji. Informują o problemach z wysyłką faktury. Mogą wskazywać na odrzucenie dokumentu XML lub niepowodzenie sesji. Oznaczają one, że wysłana faktura zawiera błędy techniczne, formalne lub związane z uprawnieniami użytkownika, przez co nie została zarejestrowana w systemie i w świetle przepisów uznaje się ją za niewystawioną. O kodach w KSeF mówi się także w związku z kodami QR, jednak chodzi tutaj o coś zupełnie innego.
Podział błędów w KSeF według kryteriów weryfikacji
Komunikaty o błędach w KSeF mogą leżeć zarówno po stronie klienta, jak i serwera oraz całego systemu. Błędy walidacji KSeF, czyli tzw. kody biznesowe mogą dotyczyć błędów w strukturze XML, błędnych danych na fakturze czy też autoryzacji i sesji.
Nie wszystkie kody oznaczają błąd. Na przykład kod 100 oznacza uwierzytelnianie w toku, a kod 200 – uwierzytelnianie zakończone sukcesem. Jednak zdecydowana większość sygnalizuje, że pojawił się jakiś problem przy wysyłce faktury, który wymaga odpowiedniej reakcji.
Można podzielić kody błędów na kilka kategorii:
- Walidacja – zakres 21xxx – błędy struktury lub formatu danych,
- Certyfikaty – 25xxx – problemy z certyfikatami KSeF,
- Duplikaty – 30xxx – konflikt z istniejącymi danymi,
- Biznesowe – 440xx – kolizje logiki biznesowej,
- Autoryzacja – 4xx HTTP – brak uprawnień lub sesji,
- Serwer – 5xx HTTP – problemy po stronie KSeF.
Najczęstsze kody błędów
Błędy dotyczące statusu sesji i uwierzytelnienia mogą zaczynać się od cyfry 4 i oznaczają:
- 415 – uwierzytelnianie zakończone niepowodzeniem – brak przypisanych uprawnień.
- 425 – uwierzytelnianie unieważnione przez użytkownika.
- 450 – uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu – nieprawidłowe wyzwanie autoryzacyjne, nieprawidłowy token lub czas tokena, token unieważniony nieaktywny, nieprawidłowe szyfrowanie lub kodowanie tokena.
- 460 – uwierzytelnianie zakończone niepowodzeniem z powodu błędu certyfikatu – np. z powodu nieważnego certyfikatu, odwołanego lub zawieszonego albo błędów weryfikacyjnych.
- 470 – uwierzytelnianie zakończone niepowodzeniem – powodem może być próba wykorzystania metod autoryzacyjnych osoby zmarłej.
- 480 – uwierzytelnianie zablokowane – podejrzenie incydentu bezpieczeństwa – w takiej sytuacji najlepiej skontaktować się z Ministerstwem Finansów przez formularz zgłoszeniowy.
Do tego są też kody odpowiedzi protokołu http:
- 401 – brak autoryzacji,
- 403 – brak uprawnień,
- 429 – przekroczony limit zapytań API,
- 500 – błąd techniczny po stronie usługi albo infrastruktury.
Prócz tego możesz spotkać się z kodami błędów aplikacyjnych (ExceptionCode):
- 21115 – nieprawidłowy certyfikat,
- 21405 – błąd walidacji danych wejściowych – niezgodność ze strukturą FA,
- 21406 – konflikt podpisu i typu uwierzytelnienia,
- 30001 – podmiot lub uprawnienie nie istnieje,
- 25008 – certyfikat nie istnieje,
- 25009 – nie można odwołać certyfikatu.
Jak reagować na błędy w KSeF?
Generalnie przy błędach 5xx najczęściej wystarczy trochę poczekać i spróbować wysłać fakturę ponownie. Jeśli problem się powtarza, warto sprawdzić status systemu KSeF na stronach rządowych.
Jeżeli KSeF odrzuci wysyłaną fakturę z powodu błędu walidacji, dokument nie zostanie przyjęty do systemu. Po usunięciu przyczyny problemu należy ponowić wysyłkę. Nie należy jednak utożsamiać całej grupy kodów 21xxx z odrzuceniem faktury – ich znaczenie zależy od konkretnej operacji i kodu.