Odbieranie faktur

Limity KSeF – ile faktur pobierzesz i ile zapytań wyślesz przez API

W skrócie

Limity KSeF to techniczne ograniczenia API opisane przez MF w dokumentacji: ile zapytań program wyśle na sekundę, minutę i godzinę, ile faktur zmieści się w sesji (10 000) i jak duży może być plik (1 MB, z załącznikiem 3 MB). Po przekroczeniu limitu KSeF zwraca błąd 429 i każe odczekać. Z limitem 10 000 zł, który do końca 2026 r. pozwala wystawiać faktury poza KSeF, nie mają nic wspólnego.

Spis treści
  1. Jak KSeF liczy limity zapytań?
  2. Jakie są limity pobierania faktur z KSeF?
  3. Ile faktur możesz wysłać?
  4. Jak duża może być faktura i ile faktur zmieści sesja?
  5. Czy na środowisku testowym limity są inne?
  6. Jak podnieść limity KSeF?
  7. Co limity oznaczają dla małej firmy?

„Limity KSeF” to techniczne ograniczenia API, które Ministerstwo Finansów opisuje w dokumentacji dla programistów: ile zapytań program wyśle na sekundę, minutę i godzinę, ile faktur zmieści się w jednej sesji i jak duży może być plik. Nie wynikają z ustawy i nie mają nic wspólnego z limitem 10 000 zł, który do końca 2026 r. pozwala wystawiać faktury poza KSeF.

Wartości podajemy za dokumentami MF w repozytorium CIRFMF: „Limity żądań API” z 14 września 2026 r. i „Limity” z 26 sierpnia 2026 r. (stan na 17 listopada 2026 r.). Te same liczby zawiera specyfikacja API produkcji w wersji 2.9.0. Wersja 2.10.0, działająca od 16 listopada 2026 r. tylko na środowisku testowym, nie zmienia dotychczasowych limitów zapytań – dodaje limit tokenów, o którym niżej.

Jak KSeF liczy limity zapytań?

  • Każda para kontekst i adres IP ma własny licznik. Kontekst to identyfikator, na który program się zalogował – NIP, identyfikator wewnętrzny albo NIP-VAT UE. MF podaje przykład: biuro rachunkowe pobiera faktury klienta ze swojego adresu IP, a klient robi to samo ze swojego – każde ma własną pulę.
  • W przesuwającym się oknie czasu. Liczy się ostatnia sekunda, ostatnie 60 sekund i ostatnie 60 minut. Liczniki nie zerują się o pełnej godzinie, a blokada zaczyna się przy pierwszym przekroczeniu któregokolwiek progu.
  • Po przekroczeniu KSeF zwraca HTTP 429 z nagłówkiem Retry-After (w sekundach). Długość blokady zależy od skali i częstotliwości przekroczeń. Inne kody błędów omawiamy w tekście o błędach uwierzytelnienia w KSeF.
  • Obchodzenie limitów, np. przez równoległe używanie wielu adresów IP w jednym kontekście, MF może uznać za zagrożenie bezpieczeństwa. Przy powtarzających się naruszeniach system może zablokować dostęp podmiotowi albo zakresowi adresów IP.
  • Zasoby publiczne, jak /auth/challenge, mają osobny limit: 60 zapytań na sekundę z jednego adresu IP.

Dwie zapowiedzi jeszcze nie działają. W godzinach 20:00–06:00 mają obowiązywać wyższe limity pobierania, ale MF nie podało ich wartości. Wersja 2.8.0 przygotowała też globalne limity liczone od adresu IP, wymierzone głównie w dostawców obsługujących wielu klientów – mechanizm jest wyłączony, a termin włączenia MF ogłosi osobno.

Jakie są limity pobierania faktur z KSeF?

Limity zapytań przy pobieraniu (req = zapytanie):

Operacja req/s req/min req/h
lista metadanych faktur (POST /invoices/query/metadata) 8 16 20
eksport paczki faktur (POST /invoices/exports) 8 16 20
status eksportu paczki 10 60 600
pobranie faktury po numerze KSeF 8 16 64

Pozostałe ograniczenia przy pobieraniu:

Ograniczenie Wartość
pozycje na stronie listy metadanych od 10 do 250 (domyślnie 10)
rekordy na jeden zestaw filtrów 10 000 – potem isTruncated i zawężasz zakres dat
zakres dat w jednym zapytaniu (lista i eksport) 100 dni w UTC (przed wersją API 2.7.1 – 3 miesiące)
paczka eksportu do 10 000 faktur lub 1 GB po kompresji, w częściach do 50 MB
równoczesne eksporty w jednym kontekście 10
dostępność statusu eksportu 7 dni
Aplikacja Podatnika od 1 do 10 faktur w jednej operacji pobrania

Dokumentacja nie wyznacza granicy, jak daleko wstecz sięgniesz – ogranicza tylko jedno zapytanie do 100 dni. Przykład: żeby pobrać faktury zakupowe od 1 lutego do 17 listopada 2026 r. (290 dni), program potrzebuje co najmniej trzech eksportów dla roli nabywcy. Jeśli któraś paczka przekroczy 10 000 faktur, dochodzi kolejny eksport od daty, na której wynik został ucięty. To nasze wyliczenie.

MF zaprojektowało pobieranie jako synchronizację z lokalną bazą programu, a nie podgląd faktur na żądanie. Program powinien odpytywać KSeF nie częściej niż co 15 minut dla każdej roli firmy na fakturze (sprzedawca, nabywca, podmiot trzeci, podmiot upoważniony). Przy 20 eksportach na godzinę MF proponuje 4 eksporty na godzinę dla każdej roli. Przy małej liczbie faktur zaleca pobieranie na żądanie i raz na dobę w nocy.

Ile faktur możesz wysłać?

Operacja req/s req/min req/h
otwarcie sesji interaktywnej 10 30 120
wysłanie faktury w sesji interaktywnej 10 30 180
zamknięcie sesji interaktywnej 20 60 240
otwarcie sesji wsadowej 10 20 60
zamknięcie sesji wsadowej 20 40 120

Przesyłanie części paczki w sesji wsadowej nie podlega limitom zapytań. Każda faktura w sesji interaktywnej to jedno zapytanie, więc jedna para kontekst i IP wyśle tak najwyżej 180 faktur na godzinę – to nasz wniosek z tabeli. Sklep internetowy, który w szczycie wystawia np. 300 faktur na godzinę, w sesji interaktywnej się nie zmieści – powinien wysyłać paczkami. MF podaje przykład sklepu, który zbiera faktury i co 5 minut wysyła je w sesji wsadowej.

Jak duża może być faktura i ile faktur zmieści sesja?

Parametr Wartość domyślna
faktura bez załącznika 1 MB (1 000 000 bajtów)
faktura z załącznikiem 3 MB
faktury w jednej sesji interaktywnej lub wsadowej 10 000 (powyżej błąd 420, zob. kody błędów KSeF)
faktury w jednym identyfikatorze zbiorczym 500 (numer KSeF w przelewie)
paczka wsadowa do 50 części po 100 MB przed zaszyfrowaniem, razem 5 GB
czas na przesłanie części paczki 20 minut razy liczba części
ważność sesji interaktywnej 12 godzin
certyfikaty KSeF (wnioski / aktywne) NIP 300 / 100, PESEL i odcisk palca certyfikatu 12 / 6

Szczegóły limitów certyfikatów omawiamy w tekście certyfikat offline KSeF. W API 2.10.0, na razie tylko na środowisku testowym, dochodzi limit liczby tokenów KSeF nowej wersji (rev2) w kontekście – przykładowa odpowiedź w specyfikacji pokazuje 100. O zmianach w tokenach piszemy w tekście token KSeF – do kiedy działa.

Aktualne wartości dla swojego kontekstu program sprawdzi zapytaniami GET /rate-limits, GET /limits/context i GET /limits/subject.

Czy na środowisku testowym limity są inne?

Na DEMO obowiązują limity skopiowane z produkcji. Co do środowiska testowego dokumenty MF się rozjeżdżają: „Limity żądań API” wciąż mówią o wartościach dziesięciokrotnie wyższych niż na produkcji, a changelog wersji 2.5.0 (maj 2026 r.) – o zrównaniu domyślnych limitów TEST z produkcyjnymi. Naszym zdaniem bezpieczniej testować z wartościami produkcyjnymi. Na TEST można je też włączyć lub ustawić własne przez /testdata/rate-limits.

Jak podnieść limity KSeF?

Na produkcji wyższy limit dostaniesz tylko na uzasadniony wniosek, poparty realną potrzebą operacyjną. Składasz go przez formularz kontaktowy ze szczegółowym opisem zastosowania. Zmiana może dotyczyć limitów zapytań, kontekstu (np. rozmiaru faktury) albo osoby (np. liczby certyfikatów na PESEL). Limit 500 faktur w identyfikatorze zbiorczym też da się zwiększyć na wniosek (FAQ KSeF 2.0, sekcja „Płatność z numerem KSeF/Identyfikatorem zbiorczym”, pyt. 14).

Co limity oznaczają dla małej firmy?

Jeśli wystawiasz i odbierasz faktury w Aplikacji Podatnika, w aplikacji mobilnej albo w e-mikrofirmie, limity API w praktyce cię nie dotyczą – to nasz wniosek, bo przy kilkudziesięciu fakturach miesięcznie trudno zbliżyć się do progów. Odczujesz najwyżej to, że w Aplikacji Podatnika jednorazowo pobierzesz do 10 faktur. Czterdzieści faktur zakupowych to więc cztery pobrania.

Z programem księgowym połączonym z KSeF limity mogą dać o sobie znać komunikatem o przekroczeniu limitu albo błędem 429. Wtedy odczekaj i nie uruchamiaj synchronizacji w kółko, bo blokada się wydłuży. Jeśli komunikat wraca codziennie, zapytaj dostawcę, jak często program odpytuje KSeF.

Biuro rachunkowe pobierające faktury 150 klientów nie dzieli jednej puli, bo limity liczą się osobno dla kontekstu każdego klienta. Może się to zmienić, gdy MF włączy zapowiadane limity globalne liczone od adresu IP – szczegółów jeszcze nie ogłoszono. Jak zorganizować same uprawnienia, piszemy w tekście uprawnienia KSeF dla biura rachunkowego.

Najczęstsze pytania

Czy w KSeF jest limit liczby faktur?

Nie ma limitu, ile faktur wystawisz lub otrzymasz w miesiącu. Są limity techniczne: do 10 000 faktur w jednej sesji, plik faktury do 1 MB (z załącznikiem do 3 MB) oraz limity liczby zapytań do API na sekundę, minutę i godzinę.

Ile faktur pobiorę naraz z KSeF?

W Aplikacji Podatnika od 1 do 10 w jednej operacji. Przez API lista metadanych ma strony do 250 pozycji i najwyżej 10 000 rekordów na jeden zestaw filtrów, a paczka eksportu mieści do 10 000 faktur lub 1 GB danych po kompresji.

Co oznacza błąd 429 w KSeF i co z nim zrobić?

Program przekroczył limit zapytań dla pary kontekst i adres IP. Musi odczekać tyle sekund, ile podaje nagłówek Retry-After. Ponawianie zapytań w pętli wydłuża blokadę.

Czy limit 10 tys. zł to limit KSeF?

To inny limit. Kwota 10 000 zł brutto miesięcznie z art. 145m ustawy o VAT pozwala do końca 2026 r. wystawiać faktury poza KSeF. Limity API określają tylko, jak intensywnie programy mogą korzystać z systemu.

Jak zwiększyć limity KSeF?

Na produkcji tylko na uzasadniony wniosek, składany przez formularz kontaktowy na ksef.podatki.gov.pl ze szczegółowym opisem zastosowania. MF radzi jednak najpierw sprawdzić, czy program korzysta z wysyłki wsadowej i eksportu paczek.

Źródła

  1. CIRFMF/ksef-api, „Limity żądań API” (14.09.2026) – naliczanie, błąd 429, tabele limitów, środowiska
  2. CIRFMF/ksef-api, „Limity” (26.08.2026) – limity na kontekst i podmiot, zwiększanie limitów
  3. CIRFMF/ksef-api, changelog API – wersje 2.5.0, 2.7.1, 2.8.0 i 2.10.0 (TEST od 16.11.2026)
  4. CIRFMF/ksef-api, „Przyrostowe pobieranie faktur” – harmonogram eksportów
  5. CIRFMF/ksef-api, „Weryfikacja faktury” – rozmiar pliku i paczki wsadowej
  6. Podręcznik użytkownika Aplikacji Podatnika KSeF 2.0 (sierpień 2026), pkt 5.3.2 – pobieranie od 1 do 10 faktur

Artykuł ma charakter informacyjny i nie stanowi porady podatkowej. W konkretnej sprawie skonsultuj się z księgowym lub doradcą podatkowym.

Przeczytaj też