Błąd 401 w KSeF – uwierzytelnienie, uprawnienia i token w API

HTTP 401 a codzienne komunikaty

Kod HTTP 401 (Unauthorized) oznacza w standardzie problem z uwierzytelnieniem – czyli potwierdzeniem, kim jest użytkownik lub system. W praktyce KSeF komunikat ten może pojawiać się także w sytuacjach, które użytkownicy odbierają jako „brak dostępu do operacji” – np. przy nieprawidłowym kontekście (NIP) albo wygasłej sesji.

Dlatego warto patrzeć szerzej: nie tylko „czy jestem zalogowany”, ale też czy działam w odpowiednim kontekście i z właściwymi uprawnieniami.

Portal (Aplikacja Podatnika) – typowe przyczyny

1. Niewłaściwy kontekst – działasz jako osoba fizyczna zamiast w kontekście firmy (lub odwrotnie), a operacja tego wymaga.
2. Brak odpowiednich uprawnień – osoba zarządzająca dostępami musi nadać uprawnienia do danej czynności (np. wystawiania faktur).
3. Opóźnienie po zmianach – po nadaniu uprawnień warto odczekać kilka minut przed ponowną próbą.

Szerszy kontekst: Przewodnik po błędach logowania.

API – token i uprawnienia

W przypadku integracji (API) sprawdź:

1. Ważność tokenu dostępowego (access token) – token ma określony czas ważności; po jego upływie konieczne jest odświeżenie sesji zgodnie z dokumentacją.
2. Zakres uprawnień w tokenie – czy token pozwala na wykonanie danej operacji (np. wysyłkę faktury).
3. Kontekst podmiotu – czy żądanie dotyczy właściwego NIP lub identyfikatora.

Jeżeli pojawia się kod 429, oznacza to limit zapytań, a nie problem z uwierzytelnieniem – patrz Komunikat limitu – portal i API.

401 a 403 w skrócie

W wielu systemach:

• 401 – problem z uwierzytelnieniem (np. brak lub wygasły token),
• 403 – użytkownik jest rozpoznany, ale nie ma uprawnień do operacji.

W KSeF komunikaty mogą być używane w sposób zależny od konkretnej sytuacji, dlatego zawsze warto sprawdzić treść komunikatu lub odpowiedzi API.

W przypadku problemów z samym logowaniem certyfikatem pomocny może być osobny artykuł: Logowanie certyfikatem – przeglądarka i kody.

Kiedy to nie jest „uprawnienia”, tylko walidacja dokumentu

Jeżeli problem pojawia się przy wysyłce faktury, przyczyną może być nie uwierzytelnienie, ale błąd w treści dokumentu (XML).

W takiej sytuacji warto sprawdzić: Walidacja XSD vs biznes

Uwaga na zbieżność liczb: komunikat „401 – weryfikacja negatywna, dokument niezgodny ze schematem xsd" to zupełnie inna sprawa. To status przetwarzania dokumentu w bramce e-Dokumenty (JPK_V7, PIT, VIU-DO), a nie HTTP 401 opisany w tym artykule — opisuje go Weryfikacja negatywna – dokument niezgodny ze schematem XSD (kod 401).

Czego KSeF nie sprawdza

Błąd 401 lub problem z tokenem dotyczy uwierzytelnienia i kontekstu dostępu, a nie jakości faktury. Poprawne logowanie do KSeF nie oznacza, że dokumenty w systemie są merytorycznie poprawne ani bezpieczne do opłacenia.

Jak można to zweryfikować automatycznie

W integracjach API warto monitorować ważność tokenów, automatycznie odświeżać sesję i reagować na alerty 401 zanim użytkownik zauważy przerwę w synchronizacji. Osobno od tego działają reguły analizy treści faktur po ich pobraniu.

FAQ

Powiązane artykuły

• KSeF token dostępowy – jak utworzyć – tworzenie tokenu dla aplikacji
• KSeF certyfikat – jak wygenerować – certyfikat do logowania w KSeF
• Błędy logowania do KSeF – przewodnik po komunikatach – interpretacja komunikatów błędów
• Logowanie do KSeF 2.0 w Aplikacji Podatnika – jak wejść do portalu i wybrać NIP

Treść ma charakter informacyjny i edukacyjny. Nie stanowi porady prawnej ani podatkowej.