Limity zapytań do API KSeF (ograniczanie żądań, 429, Retry-After)
Idea
KSeF 2.0 ogranicza liczbę żądań API, aby zapewnić stabilność działania systemu, bezpieczeństwo i równe warunki dostępu dla 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.
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.
Przykładowe obszary objęte limitami
Poniższe zestawienie ma charakter orientacyjny i nie zastępuje dokumentacji:
| Obszar | Przykładowe operacje | Charakter limitów |
|---|---|---|
| Metadane / lista | Pobieranie listy faktur lub metadanych | Limity na sekundę, minutę i godzinę |
| Eksport paczek | Tworzenie i sprawdzanie eksportu | Zwykle niższe limity niż dla prostych zapytań |
| Sesje | Otwieranie i zamykanie sesji | Osobne limity dla operacji startowych i wysyłki |
| Pojedyncza faktura | Pobranie dokumentu po numerze KSeF | Własne zestawy limitów |
Dokładne wartości limitów mogą się zmieniać. MF publikuje aktualne informacje w dokumentacji „Limity żądań API”, a w uzasadnionych przypadkach umożliwia wnioskowanie o indywidualne lub czasowe zwiększenie limitów.
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.
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
Co oznacza HTTP 429 w API KSeF?
Kod 429 (Too Many Requests) oznacza przekroczenie limitu zapytań w danym przedziale czasu. To nie jest błąd uwierzytelnienia ani walidacji faktury.
Czy po 429 mogę od razu ponowić żądanie?
Lepiej odczekać czas wskazany w nagłówku Retry-After albo zastosować rosnące
odstępy między próbami. Natychmiastowe ponawianie zwykle pogarsza sytuację.
Czy limity w środowisku testowym są takie same jak w produkcji?
Nie zawsze. Przy planowaniu integracji warto sprawdzić aktualną dokumentację MF dla obu środowisk i uwzględnić różnice w testach obciążeniowych.
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.
Przydatne serwisy
Pierwszy serwis prezentuje informacje o statusie samego KSeF, drugi – komunikaty techniczne Ministerstwa Finansów.