Błędy KSeF: kody statusów, co oznaczają i co z nimi zrobić

Spora część problemów z KSeF w sklepach i biurach rachunkowych zaczyna się od złego odczytania kodu. Ten sam numer potrafi znaczyć dwie różne rzeczy: status 450 przy logowaniu oznacza błędny token, a status 450 przy fakturze oznacza błąd weryfikacji semantyki dokumentu. Jeśli program pokazuje tylko „błąd 450”, nie wiadomo nawet, czy poprawiać fakturę, czy klucz dostępu. Poniżej zebrałem kody z oficjalnej dokumentacji API KSeF 2.0 i opisałem, co z każdym zrobić.

Trzy miejsca, w których KSeF zwraca kod błędu

• Kod HTTP odpowiedzi: 400 (błędne żądanie), 401 (brak uwierzytelnienia), 403 (brak uprawnień), 429 (przekroczony limit żądań).
• Kod wyjątku w treści odpowiedzi 400: pięciocyfrowe numery z serii 21xxx, 25xxx czy 9xxx, na przykład 21111 albo 21405.
• Kod statusu operacji: osobne tabele dla uwierzytelnienia, sesji i pojedynczej faktury. Tu pojawiają się trzycyfrowe kody 100–550.

Dobra integracja zapisuje wszystkie trzy wartości razem z polem „details”, w którym KSeF podaje konkretną przyczynę, np. numer faktury, która jest duplikatem.

Statusy faktury w KSeF: od 100 do 550

• 100, 150: faktura przyjęta i trwa przetwarzanie. To nie błąd, trzeba poczekać i sprawdzić status ponownie.
• 200: sukces, faktura ma numer KSeF.
• 405: przetwarzanie anulowane z powodu błędu sesji. Problem dotyczy całej sesji, nie tej jednej faktury.
• 410: nieprawidłowy zakres uprawnień do wystawienia faktury w tym kontekście.
• 415: brak możliwości wysłania faktury z załącznikiem. Opisuję go w osobnym tekście o statusie 415.
• 430: błąd weryfikacji pliku faktury, 435: błąd odszyfrowania pliku.
• 440: duplikat faktury. KSeF podaje numer KSeF oryginału.
• 450: błąd weryfikacji semantyki dokumentu, czyli dane niezgodne ze strukturą FA(3).
• 500: nieznany błąd, 550: operacja anulowana przez system z przyczyn wewnętrznych. Dokumentacja wprost zaleca ponowienie.

Statusy uwierzytelnienia: 415, 450, 460 i rzadsze

Przy logowaniu do API status 415 znaczy brak przypisanych uprawnień, 450 to problem z tokenem (nieprawidłowy, nieaktywny, unieważniony, źle zaszyfrowany albo z innego kontekstu), a 460 to problem z certyfikatem (nieważny, odwołany, zawieszony albo z niezaufanym łańcuchem). Status 480 oznacza zablokowane uwierzytelnienie z podejrzeniem incydentu bezpieczeństwa i wymaga kontaktu z Ministerstwem Finansów. Szczegóły i kolejność sprawdzania opisałem w tekście o błędzie uwierzytelnienia w KSeF.

Kody wyjątków 21xxx, które widać najczęściej

• 21111: nieprawidłowe wyzwanie autoryzacyjne, najczęściej wygasły challenge.
• 21301 i 21304: brak autoryzacji i brak uwierzytelnienia, czyli problem z pobraniem albo odświeżeniem tokenów po logowaniu.
• 21401: dokument niezgodny ze schemą XSD. Faktura nie przeszła walidacji struktury.
• 21405: błąd walidacji danych wejściowych w samym żądaniu.
• 21155: przekroczona dozwolona liczba faktur w sesji.
• 21180: status sesji nie pozwala na operację, np. wysyłka do zamkniętej sesji.

Które błędy ponawiać automatycznie, a których nie

Ponawiać warto 429 (po czasie z nagłówka Retry-After, więcej w tekście o limitach API KSeF), 500 i 550. Nie ma sensu ponawiać 440, 450, 410 ani 21401: każda kolejna próba skończy się tym samym, a przy limitach żądań tylko przybliży blokadę. Gdy KSeF w ogóle nie odpowiada, sprawdź komunikaty o awarii KSeF i rozważ tryb offline.

Źródła: dokumentacja API KSeF 2.0 Ministerstwa Finansów (specyfikacja OpenAPI z tabelami statusów) i serwis KSeF.