Limity API KSeF: rate limiting, HTTP 429 i Retry-After

Idea

Limity API KSeF ograniczają liczbę żądań, jakie integracja może wykonać w danym czasie — po to, by zapewnić stabilność działania systemu, bezpieczeństwo i równe warunki dostępu dla wszystkich użytkowników. Ministerstwo Finansów opisuje limity jako maksymalną liczbę operacji możliwych do wykonania w określonym czasie dla danej integracji lub kontekstu.

Dokładny sposób liczenia limitów i ich aktualne wartości należy sprawdzać w dokumentacji API KSeF 2.0, bo mogą zależeć od rodzaju operacji, środowiska i konfiguracji przyznanej integratorowi.

Istotne dla projektowania integracji jest to, że limity są wielopoziomowe: ta sama operacja ma osobny limit na sekundę, na minutę i na godzinę. Mieszczenie się w limicie sekundowym nie chroni przed przekroczeniem godzinowego, a w praktyce to właśnie limit godzinowy najczęściej okazuje się wiążący. Druga ważna rzecz: limity nie są przypisane do pojedynczej aplikacji — nalicza się je dla pary kontekst i adres IP, z którego wychodzą żądania (osobno dla każdej grupy endpointów). Kilka integracji działających na tym samym podmiocie z tego samego adresu wyjściowego dzieli jeden budżet żądań; program działający z innego adresu (np. usługa w chmurze) ma budżet niezależny od Twojej przeglądarki.

Co się dzieje po przekroczeniu

Po przekroczeniu limitu API może zwrócić kod HTTP 429 (Too Many Requests) albo szczegółowy komunikat o osiągnięciu limitu dla danej operacji.

Jeżeli odpowiedź zawiera nagłówek Retry-After, warto potraktować go jako wskazówkę, jak długo odczekać przed ponowną próbą. Limity mogą być liczone w różnych przedziałach czasu i dla różnych typów operacji.

Czas blokady nie jest stały — zależy od tego, jak bardzo i jak często limit był przekraczany. Klient, który po otrzymaniu 429 ponawia żądanie natychmiast, przedłuża własną blokadę zamiast ją skracać. Dokumentacja API opisuje też usługi pozwalające sprawdzić bieżące wartości limitów dla danego kontekstu — warto z nich skorzystać na etapie projektowania, zamiast odkrywać granice metodą prób i błędów na produkcji.

Limity API KSeF — domyślne wartości

Ministerstwo Finansów publikuje domyślne limity w dokumentacji technicznej API. Poniższe wartości pochodzą z niej i mają charakter orientacyjny — przed wdrożeniem sprawdź aktualną dokumentację, bo wartości bywają korygowane.

Pobieranie faktur

Zwróć uwagę na proporcje: zapytanie o metadane ma limit 20 na godzinę, mimo że dopuszcza 8 na sekundę. To nie pomyłka — limit godzinowy jest tu wąskim gardłem i to on decyduje o projekcie integracji. Osiem żądań w jednej sekundzie wyczerpuje niemal połowę budżetu godzinowego.

Wysyłka faktur — sesje

Sprawdzanie stanu

Sprawdzanie stanu ma limity wyraźnie wyższe niż operacje wysyłkowe — system zakłada, że po wysłaniu będziesz odpytywał o wynik. Nadal jednak warto odpytywać rozsądnie: 1200 na godzinę wyczerpuje się przy odpytywaniu co trzy sekundy.

Pozostałe operacje

Dla endpointów nieobjętych powyższymi tabelami obowiązuje limit domyślny 10 na sekundę, 30 na minutę i 120 na godzinę. Endpointy publiczne (jak pobranie wyzwania uwierzytelniającego) mają osobny limit liczony per adres IP.

Limity API KSeF zależą od środowiska

To jedna z częstszych pułapek przy wdrożeniach — integracja przechodzi testy, a na produkcji zaczyna zwracać 429:

Historycznie środowisko testowe miało limity wyraźnie wyższe niż produkcja i to właśnie stąd brało się klasyczne "na testach działało". Zmieniło się to wraz z API 2.5.0 (wdrożenie na środowisku testowym 6 maja 2026 r.): domyślne limity na TE są od tego czasu takie same jak na produkcji.

Wniosek praktyczny jest dziś inny niż przed tą zmianą: testy obciążeniowe na środowisku testowym z domyślnym profilem odwzorowują progi produkcyjne. Jeśli potrzebujesz wyższych limitów do testów, trzeba je ustawić świadomie — środowisko testowe udostępnia w tym celu endpointy grupy /testdata/rate-limits (m.in. przywrócenie profilu produkcyjnego oraz ustawienie własnych wartości). Po takim nadpisaniu wyniki znów przestają mówić cokolwiek o produkcji. Alternatywą pozostaje Demo, gdzie limity są replikowane z produkcji i nie da się ich podnieść.

Gdy domyślne limity nie wystarczają

Ministerstwo Finansów przewidziało ścieżkę dla integratorów, którym domyślne wartości nie wystarczają. Wniosek składa się przez formularz kontaktowy, zaznaczając wystąpienie w roli integratora ze sprawą techniczną dotyczącą indywidualnych limitów, wraz z uzasadnieniem opisującym rzeczywiste potrzeby operacyjne.

Zmodyfikowane limity obejmują środowisko Demo oraz produkcyjne. Komunikat w tej sprawie MF opublikowało 13 lutego 2026 r.

Zanim złożysz wniosek, warto sprawdzić, czy problemu nie da się rozwiązać projektem integracji — operacje zbiorcze i synchronizacja przyrostowa zwykle obniżają zapotrzebowanie na żądania bardziej niż podniesienie limitu.

Dobre praktyki integracji

• Ponawianie zapytań z opóźnieniem – po błędzie 429 odczekaj wskazany czas, zamiast natychmiast ponawiać żądanie.
• Stopniowe wydłużanie przerw – przy kolejnych błędach warto zwiększać odstępy między próbami (tzw. backoff).
• Operacje zbiorcze – przy większej liczbie dokumentów korzystaj z mechanizmów eksportu zamiast wielu pojedynczych zapytań.
• Synchronizacja przyrostowa – zamiast częstych pełnych odczytów, pobieraj tylko nowe lub zmienione dane.
• Testy w odpowiednim środowisku – limity w środowisku testowym mogą różnić się od produkcyjnych, dlatego warto uwzględnić to przy planowaniu.

Dokumentacja API opisuje również endpointy pozwalające sprawdzić aktualne limity – warto z nich korzystać przy projektowaniu integracji.

Jak poprawnie obsłużyć 429

Kod 429 nie jest błędem do zalogowania i pominięcia — to informacja zwrotna, że klient wysyła żądania szybciej, niż system dopuszcza. Poprawna obsługa składa się z trzech elementów.

Odczytaj Retry-After. Nagłówek podaje sugerowany czas oczekiwania w sekundach. Czas blokady jest dynamiczny — zależy od skali i częstotliwości naruszeń, więc wartość zaszyta w kodzie na sztywno prędzej czy później okaże się za krótka.

Zastosuj rosnące odstępy (backoff). Jeśli po odczekaniu żądanie znów wraca z 429, kolejna przerwa powinna być dłuższa. Typowy wzorzec to podwajanie czasu oczekiwania do rozsądnego pułapu, z niewielkim losowym rozrzutem — inaczej wszystkie instancje integracji ponowią żądania w tej samej sekundzie i wygenerują kolejny szczyt.

Nie ponawiaj w nieskończoność. Po kilku nieudanych próbach lepiej przerwać, zapisać stan i zgłosić to operatorowi, niż utrzymywać pętlę, która pogłębia problem.

Najczęstszy błąd w tym miejscu to potraktowanie 429 jak błędu sieciowego i natychmiastowe ponowienie. Efekt jest odwrotny do zamierzonego — każde ponowienie liczy się do limitu i wydłuża blokadę.

Projektowanie integracji pod limity

Limity godzinowe są w KSeF bardziej dotkliwe niż sekundowe, więc projekt integracji powinien optymalizować łączną liczbę żądań, nie ich chwilowe tempo.

Synchronizacja przyrostowa zamiast pełnych odczytów. Zapytanie o metadane ma limit 20 na godzinę. Przy pełnym odczycie całej historii przy każdym uruchomieniu wyczerpiesz go natychmiast. Pobieraj tylko dokumenty nowe lub zmienione od ostatniej synchronizacji.

Eksport paczek zamiast pojedynczych pobrań. Pobranie faktury po numerze KSeF podlega trzem progom naraz: 8 żądań na sekundę, 16 na minutę i 64 na godzinę, każdy liczony w przesuwnym oknie. Wystarczy przekroczyć dowolny z nich, żeby dostać 429 — dziewiąte pobranie w tej samej sekundzie albo siedemnaste w minucie zostanie odrzucone, choć budżet godzinowy jest ledwo napoczęty. Sto faktur dziennie rozłożonych równomiernie mieści się we wszystkich trzech z zapasem; kłopot zaczyna się przy spiętrzeniach — nadrabianiu zaległości, pierwszej synchronizacji albo przetwarzaniu całej partii tuż po jej otrzymaniu, gdzie pętla bez pauzy uderza najpierw w limit sekundowy, a dopiero potem w godzinowy. To tempo w każdym z trzech okien, a nie wolumen dobowy, decyduje o tym, czy pojedyncze pobrania wystarczą. Gdy takie spiętrzenia są regularne, mechanizm eksportu przenosi ciężar na stronę systemu i zużywa nieporównanie mniej żądań.

Rozłóż odpytywanie o stan. Po wysłaniu faktury naturalnym odruchem jest sprawdzanie wyniku w pętli. Limit 1200 na godzinę wygląda na duży, ale odpytywanie co sekundę wyczerpuje go w dwadzieścia minut. Wystarczy odpytywać co kilkanaście sekund, wydłużając odstęp przy dłuższym oczekiwaniu.

Uwzględnij inne integracje w tym samym podmiocie. Limity dotyczą pary kontekst i adres IP, nie pojedynczej aplikacji. Jeśli firma ma program księgowy i osobne narzędzie do analizy faktur wychodzące z tego samego adresu, oba zużywają ten sam budżet żądań. To częsta przyczyna 429 pojawiającego się "bez powodu" — druga integracja wykonała właśnie synchronizację. Odwrotna strona tej samej reguły: rozdzielenie ruchu na osobne adresy wyjściowe daje osobne budżety, ale nie jest to obejście limitów, tylko konsekwencja modelu naliczania — MF może je zmienić.

Co sprawdzić, zanim uznasz to za usterkę

Zanim zgłosisz 429 jako problem systemu, przejdź trzy pytania:

1. Czy na środowisku testowym nie działa nadpisany profil limitów? Domyślne limity TE są od API 2.5.0 zrównane z produkcyjnymi, ale profil ustawiony przez /testdata/rate-limits bywa źródłem złudzenia, że "przedtem działało". Limity Demo są identyczne z produkcyjnymi i nadpisać się nie dają.
2. Czy inna integracja nie zużywa tego samego budżetu? Limit dotyczy pary kontekst i adres IP — sprawdź, co jeszcze odpytuje KSeF dla tego podmiotu z tego samego adresu wyjściowego.
3. Czy klient obsługuje Retry-After? Jeśli ponawia natychmiast, sam przedłuża blokadę.

Dopiero po ich wykluczeniu warto rozważyć wniosek o indywidualne limity.

Związek z portalem

Ten sam mechanizm ograniczeń może być widoczny w przeglądarce jako komunikat "osiągnąłeś limit zapytań". Wyjaśnienie tego zjawiska znajduje się tutaj: Komunikat limitu – portal i API

Czego KSeF nie sprawdza

Przekroczenie limitu zapytań (HTTP 429) dotyczy częstotliwości komunikacji z API, a nie jakości ani poprawności faktur. Nawet po ustąpieniu limitu KSeF nadal nie weryfikuje merytorycznej treści dokumentów — to pozostaje po stronie procesu firmy.

Jak można to zweryfikować automatycznie

Integracje powinny obsługiwać 429 z nagłówkiem Retry-After i rosnącymi odstępami między próbami (backoff). Cykliczne pobieranie faktur z limitem żądań oraz operacje zbiorcze (eksport paczek) ograniczają ryzyko blokady bez rezygnacji z automatyzacji.

FAQ

Powiązane artykuły

• Komunikat "osiągnąłeś limit zapytań" w KSeF – co zrobić gdy pojawi się komunikat limitu
• KSeF API a struktura FA(3): XSD i załączniki – techniczne aspekty integracji z API
• KSeF: pobieranie faktur krok po kroku – praktyczny przewodnik po pobieraniu

Treść ma charakter informacyjny i edukacyjny. Nie stanowi porady prawnej ani podatkowej.