Błąd 405 w KSeF: „Przetwarzanie anulowane z powodu błędu sesji” i 405 w sesji wsadowej

Krajowy System e-Faktur (KSeF) oznaczył fakturę statusem 405 z opisem „Przetwarzanie anulowane z powodu błędu sesji”. Albo cała sesja wsadowa skończyła się statusem 405 z opisem „Błąd weryfikacji poprawności dostarczonych elementów paczki”. Faktura ze statusem 405 nie została przyjęta i nie ma numeru KSeF z tej wysyłki.

Dokumentacja MF podaje dla obu wariantów tylko te opisy, bez przyczyn i bez zaleceń. Poniżej czytamy je dosłownie i pokazujemy, co z nich praktycznie wynika. Pozostałe kody opisujemy na stronie z pełną listą kodów błędów KSeF.

Co oznacza kod 405

Kod 405 nie jest statusem logowania. Wśród statusów sesji interaktywnej dokumentacja go nie wymienia. Jeśli program pokazuje „405 Method Not Allowed”, to zupełnie inna sprawa: ogólny kod HTTP, który mówi, że program wysłał żądanie metodą nieobsługiwaną pod danym adresem. Dokumentacja KSeF tego wariantu nie opisuje, więc zgłoś go od razu dostawcy.

Status faktury 405

Czytając opis dosłownie: przetwarzanie tej faktury przerwano, bo zawiodła sesja, w której ją wysłano. Wniosek praktyczny jest ważny. Najpewniej KSeF nie ocenił tej faktury. Kod 405 nie mówi nic o jej treści, ani dobrego, ani złego. Przyczyna leży w sesji, a jej status ma własny kod i opis.

Po ponownej wysyłce w nowej sesji faktura może zostać przyjęta. Może też dostać własny błąd, na przykład 450, którego wcześniej nie było widać.

Nie myl 405 z kodem 550 „Operacja została anulowana przez system”. Przy 550 dokumentacja podaje przyczyny wewnętrzne systemu i zalecenie „Spróbuj ponownie”. Przy 405 winna jest sesja.

Status sesji wsadowej 405

W sesji wsadowej program pakuje faktury w archiwum ZIP, dzieli je na części, szyfruje i przesyła. Już przy otwarciu sesji deklaruje, co wyśle: rozmiar i skrót całego archiwum oraz liczbę części, a dla każdej z nich numer, rozmiar i skrót. Skrót to rodzaj odcisku palca pliku. Zmiana jednego bajtu daje inny skrót.

Opis „Błąd weryfikacji poprawności dostarczonych elementów paczki” czytamy dosłownie: to, co program dostarczył, nie przeszło sprawdzenia. Skoro KSeF zna deklarację z otwarcia sesji, najprostsze wyjaśnienie to niezgodność dostarczonych części z tą deklaracją. To nasz wniosek, nie zapis z dokumentacji.

Najczęstsze przyczyny

Faktura 405: przyczyna jest w statusie sesji

Sprawdź status sesji, w której wysłano fakturę. Programy pokazują go zwykle w historii wysyłek albo w dzienniku, razem z numerem referencyjnym sesji. Statusy błędów sesji według dokumentacji:

• 415 „Błąd odszyfrowania dostarczonego klucza” (oba rodzaje sesji), opisany w tekście o błędzie 415 w KSeF,
• 435 „Błąd odszyfrowania zaszyfrowanych części archiwum” (sesja wsadowa), opisany w tekście o błędzie 435 w KSeF,
• 430 „Błąd dekompresji pierwotnego archiwum” (sesja wsadowa), opisany w tekście o błędzie 430 w KSeF,
• 405 „Błąd weryfikacji poprawności dostarczonych elementów paczki” (sesja wsadowa), opisany niżej,
• 420 „Przekroczony limit faktur w sesji” (sesja wsadowa),
• 440 „Sesja anulowana” (oba rodzaje sesji),
• 445 „Błąd weryfikacji, brak poprawnych faktur” (oba rodzaje sesji), opisany w tekście o błędzie 445 w KSeF,
• 500 „Nieznany błąd ({statusCode})” (sesja wsadowa).

Dokumentacja nie mówi, które z tych statusów sesji powodują kod 405 przy fakturach. Dlatego zawsze zaczynaj od statusu sesji, a nie od faktury.

Sesja wsadowa 405: paczka nie zgadza się z deklaracją

Dokumentacja nie podaje przyczyn. Poniższe przyczyny to nasze wnioski z mechanizmu sesji wsadowej. Wszystkie dotyczą programu, nie treści faktur.

1. Paczka zbudowana od nowa po otwarciu sesji. Archiwum ZIP zapisuje daty plików. Program, który po przerwie albo restarcie buduje paczkę jeszcze raz, dostaje inne bajty i inne skróty, choć faktury są te same. Jak rozpoznać: 405 pojawia się po przerwanej wysyłce, którą program wznowił.
2. Część przesłana inaczej, niż zadeklarowano. Część ucięta przy przesyłaniu, zaszyfrowana ponownie z innymi danymi albo przesłana pod numerem innej części. Jak rozpoznać: 405 trafia się przy dużych paczkach dzielonych na wiele części, a małe przechodzą.
3. Inna liczba części niż w deklaracji. Program zadeklarował określoną liczbę części, a przesłał inną.
4. Skrót lub rozmiar policzony z innej wersji pliku. Na przykład z archiwum, które program potem jeszcze uzupełnił. Jak rozpoznać: 405 dostaje każda paczka, od pierwszej.

Co zrobić krok po kroku

Gdy 405 ma faktura

1. Nie poprawiaj faktury. Kod 405 nie wskazuje żadnego błędu w jej treści.
2. Znajdź numer referencyjny sesji i jej status. Zapisz kod i opis statusu sesji.
3. Usuń przyczynę według kodu sesji. Skorzystaj z poradników podlinkowanych wyżej. Przy problemach z kluczem, szyfrowaniem albo paczką to zadanie dostawcy programu.
4. Sprawdź, czy faktura nie jest już w KSeF. Zobacz, czy nie ma numeru KSeF z innej, wcześniejszej wysyłki. Jeśli ma, ponowna wysyłka skończy się kodem 440 „Duplikat faktury”. Opisujemy go w tekście o błędzie 440 w KSeF.
5. Wyślij fakturę ponownie w nowej sesji. Na próbę wysyłki do sesji, której status na to nie pozwala, dokumentacja przewiduje kod 21180 „Status sesji nie pozwala na wykonanie operacji”. Dlatego ponowną wysyłkę kieruj do nowej sesji.
6. Sprawdź status faktury po wysyłce. Teraz KSeF oceni ją samą. Dopiero ten wynik mówi coś o jej treści.

Gdy 405 ma sesja wsadowa

1. Nie poprawiaj faktur. Problem dotyczy paczki, nie ich treści.
2. Sprawdź, czy któraś faktura z paczki ma numer KSeF. Dokumentacja nie mówi, czy przy tym statusie KSeF przetworzył jakąkolwiek fakturę. Sprawdź to przed ponowną wysyłką.
3. Zgłoś błąd dostawcy programu. Podaj numer referencyjny sesji, godzinę, liczbę faktur i części oraz informację, czy wysyłkę przerwano i wznowiono.
4. Wyślij faktury w nowej sesji. Po poprawce program powinien zbudować paczkę od nowa i od razu policzyć dla niej deklarację.
5. Kiedy pisać do MF. Tylko wtedy, gdy dostawca potwierdzi, że przesłane części zgadzają się z deklaracją, a 405 wraca. Zgłoś to przez formularz MF albo na adres jpk.helpdesk@mf.gov.pl. Podaj numer referencyjny sesji i godzinę.

Jak temu zapobiec

• Po przerwanej wysyłce nie wysyłaj wszystkiego od nowa na ślepo. Najpierw sprawdź status sesji i listę faktur już przyjętych.
• Patrz na status sesji, nie tylko faktur. Jeden kod sesji wyjaśnia wtedy błędy wielu faktur naraz.

Dla programisty

Przy statusie faktury 405 nie oznaczaj faktury jako błędnej merytorycznie. Odczytaj kod i szczegóły z GET /sessions/{referenceNumber}, usuń przyczynę i wyślij fakturę w nowej sesji. Wcześniej sprawdź na liście faktur sesji, czy nie została już przyjęta. Przy sesji wsadowej 405 deklarację z otwarcia sesji licz z dokładnie tych bajtów, które potem przesyłasz. Skrót i rozmiar całego archiwum ZIP liczysz przed podziałem i szyfrowaniem, a numer, rozmiar i skrót każdej części po jej zaszyfrowaniu, SHA-256 w Base64. Zbuduj paczkę raz i przechowuj zaszyfrowane części do zamknięcia sesji. Przy wznowieniu przesyłaj te same części, nigdy archiwum zbudowane od nowa.

Nie chcesz pilnować sesji KSeF ręcznie? FakturaFlow wysyła do KSeF pojedyncze faktury, a duże partie w sesjach wsadowych. UPO pobiera sam. Gdy KSeF jest chwilowo niedostępny, ponawia wysyłkę z rosnącymi odstępami, a faktura czeka. Każdy błąd pokazuje po polsku, z informacją, co poprawić. Działa obok Twojego programu księgowego, nie zamiast niego. Załóż konto w FakturaFlow.

Podsumowanie

Status faktury 405 znaczy, że KSeF przerwał jej przetwarzanie z powodu błędu sesji, więc o samej fakturze nic jeszcze nie wiadomo. Sprawdź status sesji, usuń jego przyczynę i wyślij fakturę w nowej sesji, ale najpierw upewnij się, że nie dostała wcześniej numeru KSeF. Status sesji wsadowej 405 wskazuje na paczkę niezgodną z tym, co program zadeklarował, i to sprawa dla dostawcy. Opisy innych 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.