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
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.