Błąd 500 i 550 w KSeF: nieznany błąd i operacja anulowana przez system

Wysyłasz faktury do Krajowego Systemu e-Faktur (KSeF), a przy jednej z nich widzisz status 500 i opis „Nieznany błąd” z dodatkowym kodem w nawiasie. Albo status 550: „Operacja została anulowana przez system”, ze szczegółem „Przetwarzanie zostało przerwane z przyczyn wewnętrznych systemu. Spróbuj ponownie”. Czasem program pokazuje tylko błąd HTTP 500, 502 lub 503, bez żadnego kodu KSeF.

Te sytuacje łączy jedno: problem leży zwykle po stronie KSeF, a nie w fakturze. Z tego poradnika dowiesz się, gdzie te kody występują, jak sprawdzić, czy faktura jednak nie dotarła, i kiedy pisać do MF. Inne komunikaty opisuje pełna lista kodów błędów KSeF.

Co oznacza kod 500 i 550

Opisy kodów pochodzą ze specyfikacji API KSeF 2.0 publikowanej przez resort finansów. Numery 500 i 550 spotkasz w czterech miejscach. Trzy z nich opisuje specyfikacja, czwarte to zwykła odpowiedź HTTP. Od tego, gdzie je widzisz, zależy, co zrobić.

1. Status faktury w sesji

Każda faktura wysłana w sesji dostaje własny status. Prawidłowo przyjęta faktura ma status 200 „Sukces”. Dwa statusy oznaczają, że przetwarzanie nie doszło do skutku:

• 500 „Nieznany błąd ({statusCode})”. W miejscu {statusCode} KSeF wstawia dodatkowy kod. Zapisz go, przyda się w zgłoszeniu do MF.
• 550 „Operacja została anulowana przez system”. Szczegóły: „Przetwarzanie zostało przerwane z przyczyn wewnętrznych systemu. Spróbuj ponownie”.

Kod 550 to jedyny status faktury, przy którym MF podaje gotowe zalecenie: spróbuj ponownie. Faktura z jednym z tych statusów nie dostała w tej próbie numeru KSeF.

2. Status sesji wsadowej

Sesja wsadowa to paczka wielu faktur wysłana naraz. Cała sesja może zakończyć się statusem 500 „Nieznany błąd ({statusCode})”. Wtedy błąd dotyczy paczki, a nie jednej faktury. Kodu 550 w statusach sesji nie ma.

3. Status logowania

Przy logowaniu do KSeF program na koniec sprawdza status uwierzytelnienia. Tu również są 500 „Nieznany błąd” i 550 „Operacja została anulowana przez system”. To kod w treści odpowiedzi, a nie status HTTP. Na tym etapie żadna faktura nie została jeszcze wysłana. Odmowa z powodu tokenu KSeF ma własny kod 450 z opisem przyczyny, opisany w poradniku o błędzie 450 w KSeF. Kody 500 i 550 przy logowaniu nie znaczą więc, że token jest zły.

4. Odpowiedź HTTP z zakresu od 500 do 599

To odpowiedź serwera na samo żądanie programu, na przykład 500, 502, 503 lub 504. Żądanie nie dostało zwykłej odpowiedzi KSeF. Tu kryje się pułapka. Jeśli taki błąd przyszedł przy wysyłce faktury, program nie wie, czy KSeF zdążył ją przyjąć. Tak samo jest, gdy połączenie zerwie się, zanim przyjdzie odpowiedź.

Dwa inne kody wyglądają podobnie, ale znaczą co innego. Kod 21184 „Sesja tymczasowo niedostępna” to przerwa serwisowa w sesji i przychodzi z HTTP 400. Opisujemy go w poradniku o błędzie 21184 w KSeF. HTTP 429 to z kolei limit zapytań: KSeF każe odczekać tyle sekund, ile podaje w nagłówku Retry-After.

Najczęstsze przyczyny

Dokumentacja MF nie wyjaśnia przyczyn kodu 500. Zaliczenie go do błędów po stronie KSeF to nasze odczytanie: nie jest to jeden ze statusów, które opisują błąd w fakturze. Przy 550 dokumentacja mówi tylko, że przetwarzanie przerwano „z przyczyn wewnętrznych systemu”. Dla biura liczy się więc, w jakiej sytuacji kod się pojawił i jak ją rozpoznać.

1. Chwilowy problem po stronie KSeF

Błąd dotyczy kilku faktur naraz, różnych klientów i różnej treści, w tym samym czasie. Po ponownej wysyłce te same faktury przechodzą bez żadnej zmiany. To najprostszy przypadek. Wystarczy wysłać jeszcze raz.

2. Prace serwisowe lub awaria KSeF

Błędy trwają godzinami i kolejne próby nie pomagają. Rozpoznasz to po komunikacie MF o niedostępności lub awarii systemu. Zasady postępowania opisujemy w poradniku o trybach offline i awarii KSeF.

3. Przerwane połączenie w trakcie wysyłki

Program dostał odpowiedź HTTP z zakresu od 500 do 599 albo nie dostał odpowiedzi wcale. Przy fakturze nie ma kodu KSeF ani statusu. To najbardziej podstępna sytuacja, bo KSeF mógł fakturę przyjąć. Ślepa ponowna wysyłka jest wtedy ryzykowna.

Co zrobić krok po kroku

1. Nie poprawiaj faktury. Ani 500, ani 550 nie wskazują na treść dokumentu. Zmiana numeru faktury może wręcz zaszkodzić, jeśli pierwsza wersja jednak dotarła do KSeF.
2. Zapisz szczegóły. Kod, opis, kod w nawiasie przy 500, godzinę oraz numer sesji i faktury, jeśli program je pokazuje. Przydadzą się, gdy błąd wróci.
3. Sprawdź, czy faktura nie trafiła jednak do KSeF. Zwłaszcza po błędzie HTTP albo zerwanym połączeniu. Zobacz, czy faktura nie ma już numeru KSeF. Jeśli program na to pozwala, sprawdź status sesji i listę faktur przyjętych w tej sesji.
4. Pamiętaj, czym kończy się podwójna wysyłka. Ponowne wysłanie faktury, którą KSeF już przyjął, kończy się kodem 440 „Duplikat faktury”. W tej odpowiedzi KSeF podaje numer KSeF pierwotnej faktury. Po zerwanym połączeniu taki duplikat bywa więc dobrą wiadomością: faktura już jest w systemie. Szczegóły w poradniku o błędzie 440 w KSeF.
5. Wyślij ponownie. Przy 550 to wprost zalecenie MF. Przy 500 i błędach HTTP postępuj tak samo, gdy już wiesz, że faktura nie dotarła.
6. Jeśli błąd wraca, rób przerwy. Wysyłanie w kółko co kilka sekund nic nie da, a może skończyć się odmową z powodu limitu zapytań (HTTP 429). Odczekaj kilkanaście minut, potem dłużej.
7. Sprawdź informacje MF na portalu ksef.podatki.gov.pl. Jeśli MF ogłosiło niedostępność lub awarię KSeF, działaj według zasad trybów offline.
8. Zgłoś problem do MF, gdy błąd powtarza się przez kilka godzin mimo przerw, a MF nie opublikowało żadnego komunikatu. Zgłoś go też wtedy, gdy kod 500 wraca zawsze przy tej samej fakturze, a inne przechodzą. Kanały: formularz ksef.podatki.gov.pl/formularz lub e-mail jpk.helpdesk@mf.gov.pl. Dołącz dane z kroku 2 i nazwę środowiska (produkcja, DEMO, TEST).

Dla programisty

Traktuj odpowiedzi HTTP z zakresu od 500 do 599, przekroczone czasy oczekiwania i zerwane połączenia jako błędy przejściowe. Nie oznaczaj faktury jako odrzuconej. Ponawiaj z rosnącymi odstępami (backoff) i z limitem prób. Uważaj na żądanie wysyłki faktury: jeśli nie wiesz, czy dotarło, nie powtarzaj go na ślepo. Najpierw sprawdź status sesji i listę faktur przyjętych w sesji. Statusy faktury 500 i 550 to już odpowiedź KSeF na konkretną fakturę, więc wiadomo, że ta próba się nie udała. Gdy po ponownej wysyłce dostaniesz 440, w status.extensions znajdziesz originalKsefNumber i originalSessionReferenceNumber pierwotnej faktury. Status 500 lub 550 w odpowiedzi GET /auth/{referenceNumber} (wewnątrz HTTP 200) oznacza, że całe logowanie trzeba powtórzyć po przerwie.

Z naszej praktyki

Do października 2026 r. wysłaliśmy do produkcyjnego KSeF ponad 1 700 faktur, większość w sesjach wsadowych. Nasza kolejka traktuje odpowiedzi HTTP z zakresu od 500 do 599 i zerwane połączenia jako przejściowe. Faktura czeka i jest wysyłana ponownie. Nie trafia do odrzuconych.

Jest jeden ważny wyjątek. Jeżeli program wysłał fakturę, a połączenie zerwało się, zanim przyszła odpowiedź KSeF, nie wysyłamy jej ponownie automatycznie. KSeF mógł ją już przyjąć. Ślepa ponowna wysyłka skończyłaby się kodem 440, a gdyby numer faktury się zmienił, nawet prawdziwym duplikatem. Takie faktury po 60 minutach trafiają do sprawdzenia przez człowieka. Zasada, której się trzymamy: po przerwanym połączeniu najpierw status sesji i lista przyjętych faktur, dopiero potem ponowna wysyłka.

FakturaFlow nie gubi faktur przy błędach serwera KSeF. Gdy KSeF jest chwilowo niedostępny, faktura czeka w kolejce, a program ponawia wysyłkę z coraz dłuższymi odstępami. Każdy błąd KSeF widzisz po polsku, z informacją, co poprawić. W oknie „Szczegóły KSeF” jest historia statusów, numer KSeF i link do publicznej weryfikacji MF. FakturaFlow działa obok Twojego programu księgowego. Sprawdź, jak to działa.

Podsumowanie

Kody 500 i 550 w KSeF zwykle oznaczają błąd po stronie systemu, a nie w Twojej fakturze. Przy 550 MF wprost zaleca ponowienie. Zanim wyślesz fakturę jeszcze raz, sprawdź, czy nie dotarła już do KSeF, zwłaszcza po zerwanym połączeniu. Gdy błąd trwa godzinami, sprawdź komunikaty MF i zgłoś problem, a 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.