Krajowy System e-Faktur (KSeF) odpowiedział na żądanie Twojego programu kodem HTTP 401 „Unauthorized”. W treści odpowiedzi dokumentacja MF podaje opis „Wymagane jest uwierzytelnienie.” Programy pokazują go w historii wysyłek albo w dzienniku.
Dobra wiadomość: 401 nie dotyczy treści faktury. Oznacza, że program nie był zalogowany do KSeF. Poniżej znajdziesz przyczyny, sposób ich rozpoznania i kroki naprawy. Pozostałe kody opisujemy na stronie z pełną listą kodów błędów KSeF.
Co oznacza kod 401
401 to kod HTTP, czyli odpowiedź na jedno konkretne żądanie programu. Nie jest to status faktury, status sesji ani status logowania. W tabelach tych trzech rodzajów statusów w dokumentacji API KSeF 2.0 (repozytorium CIRF) kodu 401 w ogóle nie ma.
Znaczenie jest jedno: żądanie przyszło bez ważnego tokena dostępu. Tu łatwo o pomyłkę, bo w KSeF działają dwa różne tokeny:
- token KSeF generujesz w Aplikacji Podatnika i wklejasz w programie raz,
- token dostępu program dostaje od KSeF po każdym udanym logowaniu i jest on ważny krótko.
Program loguje się tokenem KSeF (albo certyfikatem), a potem dołącza token dostępu do każdego kolejnego żądania. Dotyczy to otwarcia sesji, wysyłki faktury, sprawdzenia statusu i pobrania UPO, czyli Urzędowego Poświadczenia Odbioru. Jeśli tokena dostępu brakuje, wygasł albo pochodzi z innego środowiska, KSeF odpowiada 401.
Osobny przypadek to sesja wsadowa. Przy przesyłaniu części paczki dokumentacja opisuje 401 jako „nieprawidłowe uwierzytelnienie”. Z opisu wynika to samo: problem z dostępem, nie z fakturami w paczce.
Praktyczny skutek dla biura: żądanie z odpowiedzią 401 nie zostało wykonane. Jeśli było to wysłanie faktury, faktura wtedy nie trafiła do KSeF. Jeśli 401 przyszło dopiero przy sprawdzaniu statusu albo pobieraniu UPO, faktura mogła zostać przyjęta wcześniej. To ważne przed ponowną wysyłką.
401, 450, 415 czy 403: jak je odróżnić
| Kod | Gdzie się pojawia | Co znaczy |
|---|---|---|
| 401 „Unauthorized” | kod HTTP żądania wysłanego po logowaniu | program nie jest zalogowany, brak ważnego tokena dostępu |
| 450 | status logowania | KSeF odrzucił token KSeF |
| 415 | status logowania | logowanie odrzucone, „Brak przypisanych uprawnień” |
| 403 „Forbidden” | kod HTTP żądania po udanym logowaniu | program jest zalogowany, ale nie wolno mu wykonać tej operacji |
Status logowania 450. Na końcu logowania program pyta KSeF o wynik i dostaje go w treści zwykłej odpowiedzi HTTP 200, w polu status.code. Wartość 450 oznacza tam „Uwierzytelnianie zakończone niepowodzeniem z powodu błędnego tokenu”. Szczegół podaje jeden z powodów: „Nieprawidłowy token”, „Token unieważniony”, „Token nieaktywny”, „Nieprawidłowy czas tokena”, „Nieprawidłowe wyzwanie autoryzacyjne”, „Nieprawidłowe szyfrowanie tokena”, „Nieprawidłowe kodowanie tokena” albo „Token nie może być użyty w kontekście …” (w miejscu kropek identyfikator kontekstu). Ten sam numer 450 oznacza też odrzuconą fakturę. Oba warianty opisujemy w tekście o błędzie 450 w KSeF.
Status logowania 415. Opis brzmi „Uwierzytelnianie zakończone niepowodzeniem”, a szczegół „Brak przypisanych uprawnień”. Numer 415 ma w KSeF jeszcze dwa inne znaczenia, jako status faktury i status sesji. Wszystkie trzy rozpisujemy w tekście o błędzie 415 w KSeF.
HTTP 403. Program jest zalogowany, ale nie może wykonać tej operacji. Przykładowy powód to missing-permissions: „Brak wymaganych uprawnień do wykonania operacji w bieżącym kontekście.” Pozostałe powody opisujemy w tekście o błędzie 403 w KSeF.
Prosta reguła: 450 i 415 to wynik logowania, 401 i 403 to kody HTTP późniejszych żądań. 401 mówi „nie wiem, kim jesteś”, 403 mówi „wiem, ale nie wolno Ci”. I jeszcze jedno: program, który po nieudanym logowaniu mimo to próbuje wysyłać, dostanie 401. Wtedy prawdziwa przyczyna siedzi w wyniku logowania, a 401 jest tylko skutkiem.
Najczęstsze przyczyny
1. Wygasł token dostępu
Token dostępu jest ważny krótko. Dobry program odświeża go sam albo loguje się ponownie. Jeśli tego nie robi, długa wysyłka może zacząć się poprawnie i urwać w połowie.
Jak rozpoznać: pierwsze faktury z serii przeszły, kolejne dostały 401. Ponowna wysyłka działa bez zmian w ustawieniach.
2. Logowanie się nie zakończyło
Program wysłał token KSeF, ale nie dostał wyniku 200 „Uwierzytelnianie zakończone sukcesem”. KSeF odrzucił logowanie (status 450 albo 415) albo program nie doczekał końca logowania, gdy status brzmiał jeszcze 100 „Uwierzytelnianie w toku”. Mimo to przeszedł do wysyłki.
Jak rozpoznać: 401 pojawia się przy każdej fakturze, od pierwszej. W dzienniku programu przed 401 widać nieudane logowanie albo nie widać logowania wcale.
3. Inne środowisko
KSeF ma trzy niezależne środowiska: produkcyjne, DEMO i TEST. Każde ma własne tokeny. Token do produkcji generujesz w Aplikacji Podatnika pod adresem ap.ksef.mf.gov.pl, token do DEMO w ap-demo, a do TEST w ap-test. Token z produkcji nie zaloguje programu w DEMO ani w TEST. Zalogowanie uzyskane w jednym środowisku nie działa w drugim.
Jak rozpoznać: w ustawieniach programu wybrane jest inne środowisko niż to, w którym powstał token. Przykład: po próbach w DEMO ktoś podmienił token na produkcyjny, a środowisko zostało stare.
4. Token KSeF przestał działać
Token mógł zostać unieważniony w Aplikacji Podatnika albo stracić uprawnienia, na których się opierał. Logowanie kończy się wtedy niepowodzeniem, na przykład statusem 450 ze szczegółem „Token unieważniony” albo „Token nieaktywny”. Program, który mimo to próbuje wysyłać, dostaje 401.
Jak rozpoznać: wczoraj działało, dziś stoją wszystkie wysyłki dla jednego NIP-u, a faktury innych klientów biura przechodzą.
5. 401 przy przesyłaniu części paczki
Ten wariant dotyczy tylko sesji wsadowej („nieprawidłowe uwierzytelnienie”). Faktury w paczce nie są tu winne. To sprawa programu, który przesyła części, więc zgłoś ją dostawcy. Nie myl go z 403 na tym samym etapie. Tam dokumentacja podaje „brak uprawnień do zapisu (np. upłynął czas na zapis)”.
Co zrobić krok po kroku
- Znajdź pierwsze 401 i sprawdź, co było przed nim. Jeśli przed 401 jest nieudane logowanie ze statusem 450 albo 415, napraw najpierw logowanie. Samo 401 zniknie razem z przyczyną.
- Sprawdź, czy faktury nie są już w KSeF. Faktura, która ma już numer KSeF, wysłana ponownie dostanie kod 440 „Duplikat faktury”.
- Uruchom wysyłkę jeszcze raz. Jeśli 401 przyszło w środku długiej serii, program powinien zalogować się od nowa.
- Sprawdź środowisko. Prawdziwe faktury wymagają środowiska produkcyjnego i tokenu z ap.ksef.mf.gov.pl. Ustawienie środowiska w programie i pochodzenie tokenu muszą się zgadzać. Różnice między środowiskami opisujemy w poradniku jak zalogować się do KSeF.
- Wygeneruj nowy token KSeF. Klient albo osoba z uprawnieniami loguje się do Aplikacji Podatnika w kontekście NIP-u firmy i w zakładce „Tokeny” generuje nowy token. Nadaj trzy uprawnienia: „Wystawianie faktur”, „Przeglądanie faktur” i „Przeglądanie historii sesji” (to ostatnie jest potrzebne do UPO). Brak uprawnień to inny błąd niż 401, ale skoro i tak generujesz token, nadaj od razu komplet. Wklej w programie cały ciąg, razem z częścią
|nip-…|. Instrukcja: jak wygenerować token KSeF. - Sprawdź ważność tokenu. Według zapowiedzi Centrum Informatyki Resortu Finansów z 10 września 2026 r. tokeny wydane do 31 grudnia 2026 r. mają działać do 30 listopada 2027 r. Nowe tokeny mają zawsze mieć termin ważności. To na razie zapowiedź, ale warto już teraz wiedzieć, kiedy powstał każdy token.
- Jeśli nic nie pomaga, zgłoś problem. Logowanie kończy się statusem 200, a już następne żądanie dostaje 401? To nie jest problem tokenu ani faktury. Zgłoś to dostawcy programu z dokładną godziną błędu. Jeśli dostawca potwierdzi, że program wysyła ważny token dostępu, napisz do MF przez formularz albo na adres jpk.helpdesk@mf.gov.pl. Podaj środowisko, NIP kontekstu, godzinę i numer referencyjny logowania.
Jak temu zapobiec
- Prowadź rejestr tokenów. Zapisz NIP klienta, datę wygenerowania, środowisko i osobę, która token wygenerowała. Gdy zapowiedziane terminy ważności zaczną obowiązywać, od razu zobaczysz, które tokeny wygasną pierwsze.
- Nie unieważniaj tokenu, którego używa program. Zmiana zakresu uprawnień wymaga nowego tokenu. Kolejność: nowy token, wymiana w programie, dopiero potem unieważnienie starego.
- Trzymaj testy w DEMO osobno. Token z DEMO nie powinien trafić do ustawień produkcyjnych i odwrotnie.
Dla programisty
Token KSeF służy tylko do logowania. Po statusie 200 w GET /auth/{referenceNumber} program wymienia tymczasowy authenticationToken na parę accessToken i refreshToken. Każde dalsze żądanie niesie accessToken w nagłówku Authorization: Bearer, a 401 znaczy, że go nie było albo jest nieważny. Zasady: nie przechodź do wysyłki bez statusu 200 przy logowaniu. Statusy 450 i 415 traktuj jako ostateczne dla danego tokenu KSeF i nie ponawiaj ich. Odświeżaj accessToken za pomocą refreshToken, zanim wygaśnie, zwłaszcza w długich sesjach wsadowych. Po 401 odśwież token (a gdy to się nie uda, zaloguj się od nowa tokenem KSeF) i powtórz żądanie jeden raz. Drugie 401 z rzędu kończy próbę: oznacz je jako błąd połączenia, nie błąd faktury, i powiadom człowieka. Pętla logowań niczego nie naprawi, a zużywa limity zapytań (HTTP 429).
Z naszej praktyki
Przy podłączaniu tokenów widzieliśmy, że token wygenerowany w produkcyjnej Aplikacji Podatnika nie działa w środowisku TEST ani DEMO. Każde z nich ma własne tokeny: DEMO z ap-demo, TEST z ap-test. KSeF odmawia wtedy logowania, choć sam token jest dobry. Odmowa logowania tokenem z produkcji w DEMO lub TEST nie oznacza więc zepsutego tokenu. Jeśli to prawdziwy token, przełącz program na środowisko produkcyjne. Nowy token nie jest potrzebny.
Druga obserwacja dotyczy statusu 450 przy logowaniu. KSeF zwrócił nam go po angielsku: Token cannot be used in nip-XXXXXXXXXX context. NIP w tym komunikacie to kontekst, o który poprosił program, a nie NIP, do którego należy token. Porównaj go z NIP-em ustawionym w programie.
Chcesz wiedzieć, czy token działa, zanim wyślesz pierwszą fakturę? FakturaFlow po zapisaniu tokenu KSeF albo certyfikatu od razu loguje się do KSeF i po polsku mówi, czy połączenie działa. Każdy błąd KSeF przy wysyłce pokazuje po polsku, z informacją, co poprawić. Działa obok Twojego programu księgowego, nie zamiast niego. Załóż konto w FakturaFlow.
Podsumowanie
Kod 401 „Unauthorized” znaczy, że program wysłał żądanie bez ważnego zalogowania do KSeF, więc faktura nie jest tu winna. Sprawdź najpierw, czy logowanie skończyło się sukcesem, potem środowisko i token. Gdy logowanie zawiodło, prawdziwą przyczynę znajdziesz w statusie 450 albo 415, a opisy pozostałych kodów na pełnej liście kodów błędów KSeF.
Stan na październik 2026 r. Opis na podstawie dokumentacji API KSeF 2.0 (wersja 2.8). Kody i komunikaty mogą się zmienić wraz z nowymi wersjami API.