Limity zapytań do API KSeF (rate limiting, 429, Retry-After)

Idea

KSeF ogranicza liczbę zapytań do wybranych endpointów, aby zapewnić stabilność działania systemu. Limity są powiązane m.in. z:

• kontekstem uwierzytelnienia (np. podmiot, NIP),
• adresem IP, z którego wysyłane są żądania.

W praktyce oznacza to, że ten sam podmiot może mieć oddzielnie liczone limity dla różnych adresów IP.

Co się dzieje po przekroczeniu

Po przekroczeniu limitu serwer zwraca kod HTTP 429 (Too Many Requests).

W odpowiedzi warto zwrócić uwagę na nagłówek Retry-After, który wskazuje, jak długo należy odczekać przed ponowną próbą. Limity mogą być liczone w różnych przedziałach czasu (np. na sekundę, minutę lub godzinę).

Przykładowe obszary objęte limitami

Poniższe zestawienie ma charakter orientacyjny i nie zastępuje dokumentacji:

Dokładne wartości limitów mogą się zmieniać – aktualne informacje znajdują się w dokumentacji Ministerstwa Finansó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