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