Wysyłasz faktury do Krajowego Systemu e-Faktur (KSeF). Część przechodzi, a przy kolejnych program zgłasza błąd HTTP 400 z kodem 21184 i opisem „Sesja tymczasowo niedostępna”. W szczegółach odpowiedzi KSeF dodaje: „Trwają prace serwisowe i sesja {referenceNumber} jest tymczasowo niedostępna. Spróbuj ponownie później lub otwórz nową sesję, aby wysłać kolejne faktury.” W miejscu {referenceNumber} stoi numer Twojej sesji.
Najważniejsze od razu: ten kod nie ocenia faktury. Mówi o sesji, nie o treści dokumentu, więc faktury nie poprawiaj. Poniżej znajdziesz, co dokładnie oznacza, co zrobić krok po kroku i jak go odróżnić od dwóch podobnych kodów. Inne komunikaty opisuje pełna lista kodów błędów KSeF.
Co oznacza kod 21184
Kod 21184 jest nowy. Pojawił się w wersji 2.8.0 API KSeF. Według historii zmian API trafił na środowisko testowe 14 września 2026 r., na DEMO 15 września 2026 r., a na produkcję 23 września 2026 r.
Dokumentacja MF mówi, że kod jest zwracany „z HTTP 400 w przypadku czasowego wstrzymania możliwości wysyłki faktur w ramach istniejącej sesji”. Zaraz potem pada zalecenie: „Rekomendowane jest otwarcie nowej sesji i kontynuowanie wysyłki.”
Kod pojawia się w jednym miejscu: przy wysyłce faktury do otwartej sesji interaktywnej (online), czyli w odpowiedzi na żądanie POST /sessions/online/{referenceNumber}/invoices. To nie jest status faktury ani status sesji. To kod wyjątku w odpowiedzi HTTP 400. Numer 21184 ma tylko jedno znaczenie, inaczej niż 415, 435 czy 440, które dla faktury znaczą co innego niż dla sesji.
Skutek dla Ciebie: KSeF nie przyjął faktury w tej próbie i nie nadał jej numeru KSeF. Trzeba ją wysłać jeszcze raz. Nie trzeba jej poprawiać.
Uważaj na sam status HTTP 400. Ten sam status może nieść około 50 różnych kodów z serii 21xxx. Część z nich naprawdę oznacza błąd w żądaniu, na przykład 21405 „Błąd walidacji danych wejściowych.”, który opisujemy w poradniku o błędzie 21405. Dlatego liczy się kod, nie sam status. A jeśli zamiast HTTP 400 widzisz odpowiedź z zakresu od 500 do 599 albo status faktury 550, to inny przypadek: błąd 500 i 550 w KSeF.
Najczęstsze przyczyny
Przyczyna techniczna jest jedna: KSeF chwilowo wstrzymał wysyłkę w Twojej sesji. Kłopoty biorą się zwykle z tego, co dzieje się wokół niej.
1. Prace serwisowe w trakcie Twojej sesji
Sesja była otwarta i przyjmowała faktury. W pewnym momencie KSeF wstrzymał wysyłkę. Rozpoznasz to po kodzie 21184, po słowach „prace serwisowe” w szczegółach i po tym samym numerze sesji przy kilku fakturach z rzędu. Wcześniejsze faktury z tej sesji mogły przejść normalnie.
2. Program traktuje 21184 jak odrzucenie faktury
Na produkcji kod działa dopiero od 23 września 2026 r. Program, który go nie zna, widzi tylko HTTP 400. Może wtedy oznaczyć fakturę jako odrzuconą albo błędną. Rozpoznasz to po statusie błędu przy fakturze i po kodzie 21184 lub słowach „Sesja tymczasowo niedostępna” w historii wysyłki albo w logu programu. Treść faktury nie ma tu żadnego znaczenia.
3. Program ponawia wysyłkę do tej samej sesji
Szczegóły od MF dopuszczają ponowienie „później”, ale MF zaleca otwarcie nowej sesji. Jeżeli program próbuje wciąż w tej samej sesji, a przerwa trwa, każda próba kończy się tak samo. Rozpoznasz to po serii kodów 21184 z tym samym numerem sesji, w krótkich odstępach.
Co zrobić krok po kroku
- Nie poprawiaj faktury. Kod 21184 dotyczy sesji, więc zmiana treści niczego nie naprawi. Zmiana numeru faktury może za to zaszkodzić. Jeśli program sam ponowi wysyłkę pierwszej wersji, w KSeF znajdą się dwie faktury na tę samą sprzedaż.
- Nie traktuj etykiety „odrzucona” jak oceny faktury. Jeśli program tak ją oznaczył, faktury nadal nie ma w KSeF. Trzeba ją wysłać, ale nie trzeba w niej niczego zmieniać.
- Przed ponowną wysyłką sprawdź status. Program mógł już sam ponowić próbę. Zobacz, czy faktura nie ma numeru KSeF. Ponowna wysyłka faktury, którą KSeF już przyjął, kończy się kodem 440 „Duplikat faktury”. Opisujemy go w poradniku o błędzie 440 w KSeF.
- Wyślij fakturę ponownie, najlepiej w nowej sesji. Tak zaleca MF. Jeżeli program otwiera nową sesję przy każdej wysyłce, wystarczy zwykłe ponowne wysłanie. Gdy kod wraca od razu, odczekaj kilka minut i spróbuj jeszcze raz.
- Jeśli 21184 wraca przez dłuższy czas, sprawdź informacje MF na portalu ksef.podatki.gov.pl. Dokumentacja MF nie opisuje kodu 21184 jako ogłoszenia niedostępności KSeF. Jeżeli MF ogłosi niedostępność lub awarię, wskazówki znajdziesz w poradniku o trybach offline i awarii KSeF.
- Zapytaj dostawcę programu, jak obsługuje kod 21184. Konkretnie: czy po tym kodzie program sam otwiera nową sesję i ponawia wysyłkę, czy oznacza fakturę jako odrzuconą.
- Napisz do MF, jeśli nowe sesje też dostają 21184 przez kilka godzin, a MF nie opublikowało żadnego komunikatu. Formularz: ksef.podatki.gov.pl/formularz, e-mail: jpk.helpdesk@mf.gov.pl. Podaj numer sesji, godzinę i pełną treść odpowiedzi.
Dla programisty
Przy POST /sessions/online/{referenceNumber}/invoices nie mapuj każdego HTTP 400 na odrzuconą fakturę. Odczytaj kod wyjątku z treści odpowiedzi. Jeżeli to 21184, zostaw fakturę w kolejce i nie licz jej do błędów. Otwórz nową sesję interaktywną i ponów wysyłkę z rosnącymi odstępami (backoff), z limitem prób. Pamiętaj, że nowa sesja to nowy klucz AES i nowy wektor IV. Generuje się je dla każdej sesji osobno i nie używa się ich w innej sesji. Zapisuj numer sesji, w której padł kod. Kody 21180 i 21173 też oznaczają problem z sesją, a nie z fakturą (opis niżej). Pozostałe kody 21xxx obsługuj jak dotąd, bo wiele z nich dotyczy samego żądania.
21184, 21180 i 21173: trzy kody o sesji
Te trzy kody łatwo pomylić. Żaden nie mówi nic o treści faktury.
| Kod | Komunikat MF | Co znaczy | Co zrobić |
|---|---|---|---|
| 21184 | „Sesja tymczasowo niedostępna.” | KSeF chwilowo wstrzymał wysyłkę w sesji | Wysłać ponownie, najlepiej w nowej sesji |
| 21180 | „Status sesji nie pozwala na wykonanie operacji.” | Sesja jest w stanie, który nie przyjmuje faktur | Otworzyć nową sesję |
| 21173 | „Brak sesji o wskazanym numerze referencyjnym.” | KSeF nie zna sesji o tym numerze | Sprawdzić numer, otworzyć nową sesję |
21180. W szczegółach KSeF pisze: „Status sesji {code} uniemożliwia wysyłkę faktur.” W miejscu {code} stoi status sesji, na przykład 170 „Sesja interaktywna zamknięta”. Różnica wobec 21184 jest ważna. Przerwa serwisowa mija, a zamknięta sesja nie otworzy się ponownie. Ponawianie wysyłki do niej nie ma sensu.
21173. Szczegóły brzmią: „Sesja … nie została odnaleziona.” Program podał numer sesji, której KSeF nie zna. Na przykład numer z błędem albo numer sesji otwartej w innym środowisku (DEMO zamiast produkcji). Ten sam kod może przyjść także przy sprawdzaniu statusu sesji. To zwykle błąd po stronie programu. Biuro nie naprawi go samo, trzeba zgłosić go dostawcy.
Jak temu zapobiec
Przerw serwisowych w KSeF nie unikniesz. Możesz uniknąć ich skutków:
- Po każdej większej wysyłce przejrzyj faktury ze statusem błędu. Te z kodem 21184 wyślij ponownie, bez poprawek.
- Nie zmieniaj faktur „na wszelki wypadek”, gdy kod mówi o sesji.
- Wybieraj program, który po kodzie 21184 sam otwiera nową sesję i ponawia wysyłkę.
Z naszej praktyki
22 września 2026 r., dzień przed wejściem kodu 21184 na produkcję, zauważyliśmy, że nasz program traktuje go jak każdy inny błąd HTTP 400. Czyli jak trwałe odrzucenie faktury. Zmieniliśmy to tego samego dnia. Dziś faktura zostaje w kolejce, program otwiera nową sesję i ponawia wysyłkę z coraz dłuższymi odstępami.
Przed tą zmianą taka faktura zostałaby oznaczona jako błędna, choć nic w niej nie było źle. Program, który nie zna kodu 21184, może robić to samo. Dlatego warto zapytać o to dostawcę (krok 6).
FakturaFlow sam ponawia wysyłkę po kodzie 21184. Gdy KSeF chwilowo wstrzymuje sesję albo odpowiada błędem serwera, faktura czeka w kolejce, a program próbuje ponownie z coraz dłuższymi odstępami. Faktura nie ginie. W oknie „Szczegóły KSeF” widzisz historię statusów każdej faktury. FakturaFlow działa obok Twojego programu księgowego, nie zamiast niego. Zobacz, jak działa FakturaFlow.
Podsumowanie
Kod 21184 „Sesja tymczasowo niedostępna” to chwilowa przerwa w sesji z powodu prac serwisowych po stronie KSeF. Faktura jest w porządku i nie wymaga poprawek. Sprawdź, czy nie ma już numeru KSeF, i wyślij ją ponownie, najlepiej w nowej sesji, tak jak zaleca MF. 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.