Błąd 21178 w KSeF: „Nie znaleziono UPO dla podanych kryteriów”

Program poprosił Krajowy System e-Faktur (KSeF) o UPO, czyli Urzędowe Poświadczenie Odbioru, i dostał odpowiedź HTTP 400 z kodem 21178 „Nie znaleziono UPO dla podanych kryteriów.”. W szczegółach KSeF podaje, czego szukał. Przykład z dokumentacji MF: „UPO o numerze KSeF {ksefNumber} i numerze referencyjnym sesji {referenceNumber} nie zostało znalezione.”.

Ten kod nie znaczy, że faktura zginęła. Znaczy tylko, że w chwili zapytania KSeF nie miał UPO dla tej pary numerów. Poniżej wyjaśniamy, skąd to się bierze i co sprawdzić po kolei. Pozostałe kody opisujemy na stronie z pełną listą kodów błędów KSeF.

Co oznacza kod 21178

21178 to kod wyjątku, czyli odpowiedź HTTP 400 na jedno konkretne żądanie programu: pobranie UPO. Nie jest to status faktury ani status sesji. W dokumentacji API KSeF 2.0 (repozytorium CIRF) ma tylko to jedno znaczenie.

Żeby go zrozumieć, trzeba wiedzieć, kiedy UPO powstaje. Dokumentacja MF (sprawdzenie stanu sesji i pobranie UPO) opisuje dwa rodzaje:

UPO sesji. Powstaje asynchronicznie, po zamknięciu sesji. Jest dostępne „po sprawdzeniu stanu sesji”. Odpowiedź o stan sesji zawiera je dopiero wtedy, „gdy sesja została zamknięta i UPO zostało wygenerowane”.
UPO faktury. Dotyczy „pojedynczej, poprawnie przyjętej faktury”. Odpowiedź o status faktury zawiera link do jego pobrania.

Przykładowy szczegół z dokumentacji łączy numer KSeF faktury z numerem referencyjnym sesji. Dotyczy więc UPO jednej faktury w konkretnej sesji. Co dokładnie zawiera UPO i jak je archiwizować, opisujemy w tekście UPO w KSeF: co to jest.

Dwa różne numery

Numer KSeF faktury i numer referencyjny sesji to dwa różne identyfikatory. Przykłady z dokumentacji MF:

numer KSeF faktury: 5265877635-20250626-010080DD2B5E-26,
numer referencyjny sesji: 20250626-SO-2F14610000-242991F8C9-B4.

Numer KSeF zaczyna się od NIP-u sprzedawcy, numer sesji od daty. Jeżeli program poda je w złych miejscach albo z różnych wysyłek, KSeF nie znajdzie UPO.

Najczęstsze przyczyny

1. Zapytanie przyszło za wcześnie

UPO sesji powstaje dopiero po jej zamknięciu, w tle. Dokumentacja MF nie mówi wprost, co KSeF odpowiada, zanim UPO będzie gotowe. Nasze doświadczenie opisujemy niżej, w części „Z naszej praktyki”. Rozpoznasz po tym, że program zapytał zaraz po wysyłce albo zanim sesja została zamknięta.

2. Faktura nie została przyjęta

UPO faktury istnieje tylko dla faktury poprawnie przyjętej. Faktura odrzucona, na przykład z kodem 450 albo 440, UPO nie ma i mieć nie będzie. Rozpoznasz po statusie faktury. Przyjęcie oznacza tylko 200 „Sukces”. Status 100 „Faktura przyjęta do dalszego przetwarzania”, mimo słowa „przyjęta”, oznacza dopiero początek przetwarzania. Status 150 „Trwa przetwarzanie” mówi sam za siebie.

Przy duplikacie (440) warto wiedzieć jedno. Odrzucenie podaje numer KSeF oryginału i numer sesji, w której KSeF go przyjął. UPO oryginału szukaj właśnie dla tej pary. Opisujemy to w tekście o błędzie 440 w KSeF.

3. Numery z różnych wysyłek

Program podał numer KSeF faktury z jednej sesji i numer referencyjny innej. Na przykład faktura przeszła dopiero za drugim razem, w nowej sesji, a program pyta o UPO w starej. Rozpoznasz po tym, że numer sesji w zapytaniu nie jest numerem sesji, w której faktura dostała status 200.

4. Pomylone identyfikatory

W miejscu numeru KSeF program podał numer sesji albo odwrotnie. Rozpoznasz po kształcie: numer KSeF zaczyna się od NIP-u sprzedawcy, a numer sesji od daty.

Co zrobić krok po kroku

Sprawdź status sesji. UPO sesji powstaje dopiero po jej zamknięciu. Jeżeli program nie zamknął sesji interaktywnej, KSeF zamknie ją sam 12 godzin po jej utworzeniu (sesja-interaktywna.md).
Sprawdź status faktury. Tylko 200 „Sukces” oznacza fakturę poprawnie przyjętą. Przy odrzuceniu UPO nie będzie. Popraw fakturę według kodu błędu i wyślij ją ponownie.
Odczekaj i zapytaj ponownie. Jeżeli sesja jest zamknięta, a faktura przyjęta, daj KSeF kilka minut. Nie pytaj w pętli co sekundę. Zapytania o status faktury w sesji mają limit 30 na sekundę, 120 na minutę i 1 200 na godzinę (limity-api.md). Po jego przekroczeniu KSeF odpowie kodem 429, opisanym w tekście o błędzie 429 w KSeF.
Sprawdź parę numerów. Numer KSeF i numer referencyjny sesji muszą pochodzić z tej samej wysyłki. Weź je z odpowiedzi, w której faktura dostała status 200. Przy duplikacie weź dane oryginału z odrzucenia.
Pobierz UPO linkiem ze statusu faktury. Odpowiedź o status faktury zawiera link do UPO. KSeF tworzy go od nowa przy każdym zapytaniu o status, a link po pewnym czasie wygasa. Jeżeli wygasł, zapytaj o status jeszcze raz i użyj nowego.
Jeżeli wszystko się zgadza, a UPO dalej nie ma, zgłoś to dostawcy programu. Podaj numer KSeF faktury i numer referencyjny sesji.

Jak temu zapobiec

Zamykaj sesję po wysyłce. UPO sesji powstaje dopiero po zamknięciu.
Pytaj o UPO po statusie 200. Najpierw status faktury, potem UPO.
Zapisuj oba numery razem. Numer KSeF i numer sesji zapisuj w chwili, gdy faktura dostaje status 200.
Ponawiaj z odstępami. Pytaj co jakiś czas, nie w pętli co sekundę.
Sprawdź uprawnienia tokenu. Token KSeF, którym program pobiera UPO, potrzebuje uprawnienia „Przeglądanie historii sesji”.

Z naszej praktyki

U nas UPO pobiera się samo, bez klikania. Odpowiedź, że nie znaleziono UPO, tuż po wysyłce zwykle oznaczała, że UPO jeszcze się generuje. Wtedy pytamy ponownie później. Większość UPO jest gotowa w ciągu kilku minut.

Do października 2026 r. wysłaliśmy do produkcyjnego KSeF ponad 1 700 faktur, większość w sesjach wsadowych. W lipcu 2026 r. dla jednego klienta poszło w ten sposób około 970 faktur w 14 sesjach. Dla wszystkich odebraliśmy UPO.

Dla programisty

21178 przychodzi jako wyjątek HTTP 400 z polami ExceptionCode, ExceptionDescription i Details. UPO sesji odczytasz z GET /sessions/{referenceNumber}: pole upo w SessionStatusResponse jest wypełnione dopiero, „gdy sesja została zamknięta i UPO zostało wygenerowane”. Dla pojedynczej faktury odpowiedź GET /sessions/{referenceNumber}/invoices/{invoiceReferenceNumber} zawiera upoDownloadUrl i upoDownloadUrlExpirationDate. Link nie wymaga tokena dostępu, powstaje przy każdym zapytaniu o status, nie podlega limitom zapytań i wygasa. Nie zapisuj go więc na później, zapisuj samo UPO. Dopóki sesja nie ma UPO albo faktura nie osiągnęła statusu 200, traktuj 21178 jako stan przejściowy. Potem szukaj błędu w parze numerów.

Nie chcesz pilnować UPO ręcznie? FakturaFlow wysyła pojedyncze faktury i duże paczki w sesjach wsadowych, a UPO pobiera sam. W oknie „Szczegóły KSeF” widzisz historię statusów faktury, numer KSeF i link do publicznej strony weryfikacji MF. Działa obok Twojego programu księgowego, nie zamiast niego. Załóż konto w FakturaFlow.

Podsumowanie

Kod 21178 znaczy, że w chwili zapytania KSeF nie miał UPO dla podanej pary numerów. Sprawdź po kolei, czy sesja jest zamknięta, czy faktura ma status 200 i czy numer KSeF pochodzi z tej samej sesji. Jeżeli wszystko się zgadza, odczekaj i zapytaj ponownie. Pozostałe kody opisuje pełna lista 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.