Błąd 403 w KSeF: „Forbidden”. Sześć powodów odmowy i co z nimi zrobić

Program wysłał żądanie do Krajowego Systemu e-Faktur (KSeF) i dostał kod HTTP 403 „Forbidden”. W treści odpowiedzi jest pole reasonCode z krótkim powodem po angielsku, na przykład missing-permissions, oraz opis po polsku. Programy pokazują go w historii wysyłek albo w dzienniku.

403 nie dotyczy treści faktury. KSeF mówi nim: wiem, kim jesteś, ale tego Ci nie wolno. Poniżej znajdziesz wszystkie powody odmowy i kroki naprawy. Pozostałe kody opisujemy na stronie z pełną listą kodów błędów KSeF.

Co oznacza kod 403

403 to kod HTTP, czyli odpowiedź na jedno konkretne żądanie programu. Może to być otwarcie sesji, wysłanie faktury, sprawdzenie statusu albo pobranie UPO (Urzędowego Poświadczenia Odbioru). Program jest wtedy zalogowany, ale tej operacji wykonać mu nie wolno. Żądanie z odpowiedzią 403 nie zostało wykonane.

Tak wygląda 403 na tle podobnych kodów:

Brak zalogowania opisujemy w tekście o błędzie 401 w KSeF.

Wszystkie powody odmowy (reasonCode)

Dokumentacja API KSeF 2.0 (repozytorium CIRF) wymienia sześć wartości reasonCode:

Osobny przypadek to przesyłanie części paczki w sesji wsadowej. Tam dokumentacja opisuje 403 jako „brak uprawnień do zapisu (np. upłynął czas na zapis)”. Omawiamy go niżej.

Dokumentacja podaje tylko te opisy, bez przyczyn i zaleceń. Kolumna „Co zrobić” i przyczyny poniżej to nasze wnioski z zasad uprawnień i logowania, nie oficjalny komentarz MF.

Najczęstsze przyczyny

1. missing-permissions: brak uprawnienia do tej operacji

Program zalogował się poprawnie, więc w tym NIP-ie ma jakieś uprawnienie. Nie ma jednak tego, którego wymaga operacja. Według dokumentacji MF do otwarcia sesji i wysyłki faktur potrzebne jest uprawnienie do wystawiania faktur. W Aplikacji Podatnika nazywa się ono „Wystawianie faktur”.

Z naszej praktyki program, który wysyła faktury i odbiera UPO, potrzebuje trzech uprawnień:

• „Wystawianie faktur”, do wysyłki,
• „Przeglądanie faktur”, do pobierania faktur z KSeF,
• „Przeglądanie historii sesji”, do pobierania UPO.

Jak rozpoznać typowe sytuacje:

• Logowanie przechodzi, 403 przychodzi przy otwarciu sesji. Token powstał bez uprawnienia „Wystawianie faktur”, na przykład tylko do pobierania faktur zakupowych.
• Faktury wychodzą, a 403 przychodzi przy pobieraniu UPO. Brakuje uprawnienia „Przeglądanie historii sesji”. Faktury mogły już zostać przyjęte, więc nie wysyłaj ich ponownie.
• Certyfikat księgowej działa u jednych klientów, a u innych daje 403. Ci drudzy nadali jej tylko przeglądanie faktur, bez wystawiania.

Kto nadaje uprawnienia:

• Token KSeF dostaje uprawnienia w chwili generowania. Zakresu nie da się potem zmienić. Właściciel NIP-u albo osoba z prawem zarządzania uprawnieniami generuje nowy token z trzema uprawnieniami, a Ty podmieniasz go w programie. Instrukcję znajdziesz w poradniku jak wygenerować token KSeF.
• Certyfikat nie niesie uprawnień. Klient nadaje je osobie lub firmie, na którą wydano certyfikat, w Aplikacji Podatnika, w zakładce „Uprawnienia”. Biuro może też dostać uprawnienie jako podmiot.

Uprawnienia do samofakturowania, faktur RR i działania jako przedstawiciel podatkowy to osobna grupa. Nadaje je tylko właściciel albo administrator z prawem zarządzania uprawnieniami. Dokumentacja podaje, że KSeF sprawdza je w procesie walidacji faktur. Z tego wynika, że ich brak wyjdzie raczej przy konkretnej fakturze niż jako 403 przy otwarciu sesji.

Jeśli program nie ma w danym NIP-ie żadnego uprawnienia, nie zaloguje się wcale. Wtedy zamiast 403 zobaczysz status logowania 415 (błąd 415 w KSeF).

2. ip-not-allowed: żądanie z innego adresu IP

Opis brzmi „Żądanie pochodzi z adresu IP innego niż wskazany podczas uwierzytelnienia.” Z jego brzmienia wynika, że przy logowaniu wskazano adres IP, z którego mają przychodzić dalsze żądania. Kolejne żądanie przyszło z innego adresu, więc KSeF je odrzucił. Najpewniej chodzi o to, że zalogowanie przypięte do adresu nie zadziała z innego miejsca, nawet jeśli ktoś je przechwyci.

Typowe sytuacje:

• Program działa na kilku serwerach albo w chmurze. Loguje się z jednego adresu, a fakturę wysyła z innego. Jak rozpoznać: 403 pojawia się nieregularnie, a ponowna wysyłka raz przechodzi, raz nie.
• VPN przełącza serwer. Jak rozpoznać: błędy zaczynają się po ponownym połączeniu z VPN i dotyczą wszystkich NIP-ów naraz.
• Biuro przechodzi na zapasowe łącze albo dostawca internetu zmienia adres. Jak rozpoznać: logowanie było rano, a 403 przyszło w środku dłuższej wysyłki.

Co zrobić: zanotuj godzinę i sprawdź, czy w tym czasie zmieniło się połączenie. Uruchom wysyłkę jeszcze raz. Program, który loguje się od nowa, zrobi to już z obecnego adresu. Jeśli błąd wraca, przekaż dostawcy programu godzinę, reasonCode i opis sieci: VPN, kilka komputerów, zapasowe łącze. Trwała naprawa leży po stronie programu. Logowanie i dalsze żądania muszą wychodzić z tego samego adresu.

3. Pozostałe powody

security-service-blocked. Żądanie zatrzymały mechanizmy bezpieczeństwa KSeF. Dokumentacja nie mówi, co je uruchamia. Nie ponawiaj żądania w pętli. Sprawdź, kto ma dostęp do Twoich tokenów i certyfikatów. Jeśli odmowa się powtarza, zgłoś ją przez formularz MF z godziną, NIP-em i numerem sesji. Blokadę samego logowania opisujemy w tekście o błędzie 480 w KSeF.

auth-method-not-allowed. Tej operacji nie da się wykonać metodą, którą program się zalogował, na przykład tokenem albo certyfikatem. Dokumentacja nie podaje listy takich operacji. Przekaż sprawę dostawcy programu: operację trzeba wykonać po zalogowaniu inną metodą.

insufficient-resource-access. Program pyta o zasób, do którego nie ma dostępu, na przykład o sesję, fakturę albo UPO. Możliwy scenariusz: program przełączył się na NIP innego klienta, a pyta o sesję otwartą w poprzednim. Sprawdź, czy program jest zalogowany w tym samym NIP-ie, w którym powstała sesja lub faktura.

context-type-not-allowed. Przy logowaniu wybiera się kontekst, na przykład NIP albo identyfikator wewnętrzny. Ta operacja nie jest dostępna dla typu, w którym program się zalogował. Jeśli to możliwe, zaloguj program w kontekście NIP-u.

4. 403 w sesji wsadowej: upłynął czas na zapis

W sesji wsadowej program przesyła zaszyfrowaną paczkę w częściach. Przy tym etapie dokumentacja opisuje 403 jako „brak uprawnień do zapisu (np. upłynął czas na zapis)”. Według opisu sesji wsadowej na każdą część przypada 20 minut. Łączny czas to liczba części razy 20 minut.

Jeśli czas minie, sesja kończy się statusem 440 „Sesja anulowana” ze szczegółem „Przekroczono czas wysyłki” (błąd 440 w KSeF). Przy zamykaniu takiej sesji program może też dostać kod 21208 „Czas oczekiwania na requesty upload lub finish został przekroczony.”

Jak rozpoznać: 403 pojawia się w trakcie przesyłania części, a sesja ma potem status 440.

Co zrobić: sprawdź status sesji i listę faktur przyjętych w niej przez KSeF. Faktury, których tam nie ma, wyślij w nowej sesji wsadowej, najlepiej przy stabilnym łączu. Każda część może mieć do 100 MB przed zaszyfrowaniem.

Co zrobić krok po kroku

1. Odczytaj reasonCode. Bez niego 403 mówi niewiele. Jeśli program pokazuje samo „403”, poproś dostawcę o pełną odpowiedź z dziennika.
2. Ustal, przy jakiej operacji przyszła odmowa: otwarcie sesji, wysyłka, status, UPO czy przesyłanie części paczki.
3. Sprawdź, czy faktura nie jest już w KSeF. 403 przy wysyłce znaczy, że ta wysyłka się nie odbyła. 403 przy statusie albo UPO znaczy, że faktura mogła zostać przyjęta wcześniej. Ponowna wysyłka przyjętej faktury skończy się kodem 440 „Duplikat faktury”.
4. Usuń przyczynę według tabeli. Przy missing-permissions to nowy token z trzema uprawnieniami albo uprawnienie nadane przez klienta. Przy ip-not-allowed to stały adres, z którego program pracuje.
5. Zaloguj program od nowa i powtórz operację.
6. Napisz do MF tylko przy blokadzie. Powtarzający się security-service-blocked zgłoś przez formularz albo na adres jpk.helpdesk@mf.gov.pl. Pozostałe powody rozwiązuje się po stronie uprawnień albo programu.

Jak temu zapobiec

• Generuj tokeny od razu z trzema uprawnieniami: „Wystawianie faktur”, „Przeglądanie faktur”, „Przeglądanie historii sesji”.
• Zmieniaj uprawnienia w dobrej kolejności. Nowy token, podmiana w programie, dopiero potem unieważnienie starego.
• Zapisuj, z jakimi uprawnieniami powstał każdy token. Przy 403 od razu wiesz, czego brakuje.
• Daj programowi jeden stały adres. Uprzedź dostawcę, jeśli biuro korzysta z VPN albo zapasowego łącza.

Dla programisty

Reaguj na reasonCode, a nie na sam kod 403. missing-permissions, auth-method-not-allowed, insufficient-resource-access i context-type-not-allowed to błędy konfiguracji: ponowienie nic nie da, pokaż użytkownikowi powód. Przy ip-not-allowed zaloguj się od nowa z bieżącego adresu albo zadbaj, żeby logowanie i wszystkie żądania wychodziły z jednego adresu. Przy security-service-blocked wstrzymaj żądania w tym kontekście. Według dokumentacji uprawnień otwarcie sesji interaktywnej i wysyłka w niej wymagają jednego z uprawnień InvoiceWrite, PefInvoiceWrite lub EnforcementOperations. Sesja wsadowa wymaga InvoiceWrite lub EnforcementOperations. Po 403 nigdy nie oznaczaj faktury jako błędnej merytorycznie.

Wolisz widzieć błędy KSeF po polsku? FakturaFlow pokazuje każdy błąd KSeF po polsku, z informacją, co poprawić. Po zapisaniu tokenu KSeF albo certyfikatu od razu loguje się do KSeF i mówi, czy połączenie działa. Wysyła pojedyncze faktury i duże paczki, a UPO pobiera sam. Działa obok Twojego programu księgowego. Załóż konto w FakturaFlow.

Podsumowanie

Kod 403 „Forbidden” znaczy, że program jest zalogowany, ale tej operacji wykonać mu nie wolno. O przyczynie mówi reasonCode. Dla biura najważniejsze są dwa: missing-permissions, czyli brak uprawnienia w tokenie lub u właściciela certyfikatu, oraz ip-not-allowed, czyli zmiana adresu IP w trakcie pracy. 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.