Błędy KSeF w zwykłym języku: kod, przyczyna, pole, naprawa

Komunikaty błędów KSeF to główna skarga UX na rynku po starcie. System zwraca numeryczne kody wyjątków (21401, 21405, 21301, 440) z opisami klasy deweloperskiej jak „Dokument nie jest zgodny ze schemą XSD." Żaden polski dostawca nie dostarcza wyjaśnienia w zwykłym języku. Kody są deterministyczne, co czyni je idealnymi dla tłumaczenia uziemionego w cytatach: każdy kod mapuje do jednej przyczyny, jednego błędnego pola i jednej naprawy.

Dekoder

21401: „Dokument nie jest zgodny ze schemą XSD"

Zwykły język: XML Twojej faktury nie pasuje do schematu FA(3). Struktura jest błędna.

Przyczyna: XML został wygenerowany z przestarzałego szablonu (FA(2) zamiast FA(3)), zawiera nieprawidłowe znaki (bajty BOM), ma elementy w złej kolejności lub brakuje elementów obowiązkowych.

Błędne pole: Odpowiedź błędu zawiera XPath do błędnego elementu. Szukaj ścieżki pola w odpowiedzi.

Naprawa: Wygeneruj fakturę ponownie z aktualnego szablonu FA(3). Zaktualizuj oprogramowanie fakturowe do najnowszej wersji. Nie edytuj XML ręcznie.

21405: Błąd walidacji danych wejściowych

Zwykły język: Konkretne pole zawiera dane w złym formacie. Struktura XML jest poprawna, ale treść jednego pola nie przechodzi walidacji.

Przyczyna: NIP z myślnikami lub spacjami, data w złym formacie, pole numeryczne z przecinkiem zamiast kropki, lub KursWaluty z mniejszą liczbą niż 6 miejsc po przecinku.

Błędne pole: Odpowiedź błędu nazywa konkretne pole. Częściowi winni: NIP (nabywcy lub sprzedawcy), P_1 (data wystawienia), KursWaluty.

Naprawa: Popraw dane źródłowe w karcie kontrahenta lub formularzu faktury. Dla NIP: usuń wszystkie myślniki, spacje i prefiksy „PL". Dla dat: użyj YYYY-MM-DD. Dla ułamków: użyj kropki, nie przecinka. Wyślij ponownie.

21301: „brak autoryzacji"

Zwykły język: Nie masz uprawnień do wystawiania faktur dla NIP w nagłówku faktury.

Przyczyna: Twój token wygasł, został wystawiony dla innego NIP, lub Twoje uprawnienia nie obejmują praw wystawiania dla tego podmiotu.

Błędne pole: NIP w nagłówku faktury vs NIP na tokenie.

Naprawa: Wygeneruj token ponownie z odpowiednimi zakresami dla NIP wystawiającego. Jeśli używasz logowania osobistego (Profil Zaufany), przełącz na autoryzację tokenem. Jeśli jesteś biurem rachunkowym, zweryfikuj, że klient nadał Ci uprawnienia wystawiania dla swojego NIP.

440: Duplikat

Zwykły język: Faktura z tym samym numerem od tego samego wystawcy już istnieje w KSeF.

Przyczyna: Wysłałeś ponownie fakturę, która została już pomyślnie wysłana. Pierwsze wysłanie powiodło się, ale nie sprawdziłeś statusu przed ponownym wysłaniem.

Błędne pole: Numer faktury (NrFaktury).

Naprawa: Odpytaj KSeF po własnym numerze faktury. Jeśli pierwsze wysłanie powiodło się (status 200), użyj istniejącego numeru KSeF. Nie twórz duplikatu. Jeśli pierwsze wysłanie faktycznie nie powiodło się, napraw błąd i wyślij ponownie z tym samym numerem faktury.

Status 100 lub 150: To nie błąd

Zwykły język: Twoja faktura jest przetwarzana. Czekaj.

Przyczyna: KSeF przyjął fakturę i ją przetwarza. Czas przetwarzania waha się od sekund do godzin pod obciążeniem.

Naprawa: Odpytuj tę samą sesję. Nie wysyłaj ponownie. Ponowne wysłanie tworzy duplikat.

HTTP 500, 503, 429: Błąd serwera

Zwykły język: KSeF jest przeciążony lub ogranicza Twoje zapytania.

Przyczyna: Ruch w okresie startu, przejściowe problemy infrastruktury, lub zbyt wiele zapytań w krótkim oknie.

Naprawa: Retry z wycofaniem (backoff). Jeśli błąd utrzymuje się, przełącz na tryb offline24. Wystaw fakturę lokalnie i wyślij do następnego dnia roboczego.

Dlaczego żaden dostawca tego nie dostarcza

Kody błędów są deterministyczne. Mapują do stałych przyczyn i napraw. Silnik wyjaśnienia jest technicznie prosty: tabela od kodu do przyczyna-pole-naprawa, z cytatami do oficjalnej dokumentacji.

Żaden polski dostawca tego nie dostarcza, ponieważ incumbenci zostali zbudowani przed KSeF i traktują obsługę błędów jako dodatek. Ich komunikaty błędów to surowe odpowiedzi API opakowane w cienki UI. Użytkownik widzi „21401" i musi szukać w sieci wyjaśnienia, gdzie znajduje artykuły z farm treści ze zmyślonymi kodami.

Okazja to dostarczenie silnika wyjaśnienia jako darmowe, autentycznie przydatne narzędzie. Każdy kod błędu w prawdziwej taksonomii, zmapowany do zwykłego języka, z cytatami do oficjalnej dokumentacji OpenAPI. Bez zmyślonych kodów. Bez wymyślonych procedur. Użytkownik szuka „błąd 21401 KSeF" i znajduje stronę, która mówi: „Twój XML nie pasuje do schematu FA(3). Oto dlaczego. Oto pole do naprawienia. Oto jak to naprawić."

Ta strona rankuje. Rankuje, bo jest dokładna, źródłowa i przydatna. Rankuje, bo każda alternatywa z farmy treści jest błędna. Dokładność to fosa.

Compliance AI Act

Jeśli silnik wyjaśnienia używa AI (np. model językowy do generowania tekstu w zwykłym języku z kodu i kontekstu), AI Act art. 50 wymaga ujawnienia, że użytkownik wchodzi w interakcję z systemem AI i czytelnej maszynowo marki treści generowanej przez AI. Od 2 sierpnia 2026 to obowiązkowe.

Bezpieczniejszy projekt: deterministyczna tabela, nie model językowy. Kody są stałe. Przyczyny są stałe. Naprawy są stałe. Tabela jest bardziej dokładna, szybsza i zwolniona z obowiązków przejrzystości AI Act. Używaj AI do rzeczy, które korzystają z rozumowania (sugestie parametrów, szkicowanie). Używaj tabeli do rzeczy, które są deterministyczne (kody błędów).

Niniejszy materiał ma charakter informacji ogólnej i nie stanowi porady prawnej ani podatkowej. W konkretnej sytuacji zweryfikuj aktualne przepisy lub skonsultuj się z doradcą.