Błąd 480 w KSeF: „Uwierzytelnienie zablokowane”. Co zrobić przy podejrzeniu incydentu

Program próbował zalogować się do Krajowego Systemu e-Faktur (KSeF) i dostał status 480 „Uwierzytelnienie zablokowane”. Szczegół brzmi: „Podejrzenie incydentu bezpieczeństwa. Skontaktuj się z Ministerstwem Finansów przez formularz zgłoszeniowy.”

Komunikat brzmi groźnie, ale da się go obsłużyć spokojnie i po kolei. Poniżej znajdziesz, co oznacza, czego nie robić, co przygotować do zgłoszenia i co sprawdzić u siebie. Pozostałe kody opisujemy na stronie z pełną listą kodów błędów KSeF.

Co oznacza kod 480

480 to status logowania. Na końcu logowania program pyta KSeF o wynik (GET /auth/{referenceNumber}). Odpowiedź przychodzi z kodem HTTP 200, a 480 jest wartością pola status.code w jej treści. To nie jest kod HTTP, status faktury ani status sesji. W dokumentacji API KSeF 2.0 numer 480 występuje tylko wśród statusów logowania.

Oficjalny opis to „Uwierzytelnienie zablokowane”. Szczegół zawiera dwie informacje. Pierwsza to powód: „Podejrzenie incydentu bezpieczeństwa”. Druga to polecenie: „Skontaktuj się z Ministerstwem Finansów przez formularz zgłoszeniowy”. To rzadki przypadek, w którym MF pisze wprost, co zrobić. Nie każe ponawiać logowania. Każe się skontaktować.

Skutek dla biura: logowanie się nie udało, więc program nie otworzył sesji. Faktury, które czekały na tę wysyłkę, nie trafiły do KSeF. To nie jest błąd treści faktury.

Nie myl 480 z dwoma podobnymi kodami:

• HTTP 403 z powodem security-service-blocked („Żądanie zostało zablokowane przez mechanizmy bezpieczeństwa.”). To odpowiedź HTTP na pojedyncze żądanie, a nie wynik logowania. Opisujemy go w tekście o błędzie 403 w KSeF.
• Status logowania 450 ze szczegółem „Token unieważniony”. To unieważniony token, a nie blokada. Zwykle wystarcza nowy token (błąd 450 w KSeF).

Przyczyny blokady: co wiadomo, a czego nie

Dokumentacja MF podaje tylko opis i szczegół. Nie mówi, co uruchamia blokadę, jak długo trwa ani czego dokładnie dotyczy: jednego tokenu, jednej osoby czy całego NIP-u. Nie będziemy tego zgadywać.

Z Twojej strony liczą się dwie możliwości:

1. Incydent jest prawdziwy. Ktoś inny ma Twój token KSeF albo klucz prywatny certyfikatu i próbuje go użyć.
2. Incydentu nie ma. Mechanizm bezpieczeństwa zareagował na coś, co było zwykłą pracą Twojego programu.

Rozstrzygnie to dopiero MF. Pierwszą możliwość możesz jednak sprawdzić sam, od razu. Sygnały, że problem może leżeć po Twojej stronie:

• token był wysłany zwykłym e-mailem albo leży we wspólnym arkuszu lub folderze,
• nikt nie pamięta, komu i kiedy przekazano token,
• klucz prywatny certyfikatu leży w jednym folderze z hasłem,
• z firmy odszedł ktoś, kto miał dostęp do tokenów lub certyfikatów,
• w Aplikacji Podatnika widać faktury, których nikt z Was nie wysyłał.

Co zrobić krok po kroku

1. Zatrzymaj automatyczne próby. Jeśli program sam ponawia logowanie, wstrzymaj wysyłkę dla tego NIP-u. Nic w dokumentacji nie wskazuje, że blokada mija po kolejnej próbie. Komunikat wskazuje jedną drogę: kontakt z MF.

2. Zapisz dane próby logowania. Przydadzą się w zgłoszeniu:

   • numer referencyjny próby logowania, czyli referenceNumber z zapytania o jej status,
   • NIP (kontekst), w którym program się logował,
   • datę i godzinę próby,
   • metodę logowania: token KSeF, certyfikat KSeF, podpis lub pieczęć kwalifikowana,
   • środowisko: produkcyjne, DEMO czy TEST,
   • nazwę programu i, jeśli go znasz, adres IP, z którego program się łączy,
   • pełną treść odpowiedzi.

   Zrób to od razu. KSeF przechowuje status logowania przez 7 dni. Później zapytanie o niego zwraca HTTP 410 „Gone” z opisem „Operacja wygasła i nie jest już dostępna.” (błąd 410 w KSeF). Jeśli Twój program pokazuje tylko „błąd logowania”, poproś dostawcę o wpis z dziennika z numerem referencyjnym.

3. Ustal zasięg. Sprawdź w dzienniku programu, czy 480 dostały wszystkie obsługiwane NIP-y, czy tylko jeden. Nie wywołuj w tym celu nowych logowań.

4. Sprawdź bezpieczeństwo u siebie. Przejdź listę sygnałów z poprzedniej sekcji. Jeśli token mógł wyciec, poproś właściciela NIP-u o nowy token w Aplikacji Podatnika i unieważnij stary (jak wygenerować token KSeF). Jeśli mógł wyciec klucz certyfikatu, unieważnij certyfikat z powodem „Klucz prywatny powiązany z certyfikatem został skompromitowany” i wystąp o nowy (certyfikat KSeF). Nowy token nie musi zdjąć blokady. Wymieniasz go dla bezpieczeństwa, nie po to, żeby obejść 480.

5. Wyślij zgłoszenie przez formularz. Szczegół wskazuje formularz MF, więc zacznij od niego. Wpisz dane z kroku 2 i to, co już zrobiłeś w kroku 4, z datami. Dodatkowy kanał kontaktu z MF to adres jpk.helpdesk@mf.gov.pl.

6. Poinformuj klienta. Jeśli jesteś biurem rachunkowym i program logował się w kontekście NIP-u klienta, powiedz mu o blokadzie. Ustalcie, kto pisze do MF, i przekaż mu kopię zgłoszenia.

7. Wznów wysyłkę ostrożnie. Po odpowiedzi MF zaloguj się raz, na próbę, zanim włączysz wysyłkę hurtową. Faktury, które czekały, wyślij dopiero po statusie 200.

Jak temu zapobiec

MF nie publikuje, co uruchamia blokadę, więc nie obiecujemy, że te zasady jej zapobiegną. Ograniczają za to ryzyko prawdziwego incydentu:

• Przekazuj token kanałem szyfrowanym, nie zwykłym e-mailem.
• Nadawaj tokenowi tylko potrzebne uprawnienia. Program wysyłający faktury potrzebuje trzech: „Wystawianie faktur”, „Przeglądanie faktur” i „Przeglądanie historii sesji”. Biuro nie potrzebuje „Zarządzania uprawnieniami”.
• Jeden token na jeden program. Gdy zmieniasz program, unieważnij token, którego używał stary.
• Prowadź rejestr tokenów: NIP, data wygenerowania, środowisko, kto wygenerował i gdzie token jest używany.
• Trzymaj klucz prywatny certyfikatu osobno od hasła. Certyfikatu wydanego na PESEL nie udostępniaj innym osobom.
• Wymieniaj tokeny po odejściu pracownika, który miał do nich dostęp.

Dla programisty

Traktuj 480 jako stan końcowy, a nie błąd przejściowy. Nie ponawiaj logowania automatycznie i zatrzymaj kolejkę dla tego kontekstu. Zapisz referenceNumber próby i pokaż go użytkownikowi razem z dosłownym szczegółem, żeby trafił do zgłoszenia. Po 7 dniach GET /auth/{referenceNumber} zwraca 410, więc numer i odpowiedź trzymaj we własnym dzienniku.

Po wymianie tokenu chcesz mieć pewność, że logowanie działa? 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 pokazuje po polsku, z informacją, co poprawić. To niezależne narzędzie, które działa obok Twojego programu księgowego. Zobacz, jak działa FakturaFlow.

Podsumowanie

Status 480 „Uwierzytelnienie zablokowane” to blokada logowania z powodu podejrzenia incydentu bezpieczeństwa. Nie ponawiaj prób. Zapisz numer referencyjny i szczegóły, sprawdź, kto ma dostęp do Twoich tokenów i certyfikatów, i napisz do MF przez formularz. Opisy pozostałych kodów znajdziesz 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.