KSeF 429 Too Many Requests: limity API, Retry-After i jak nie blokować wysyłki faktur

Sklep, który wysyła faktury do KSeF pojedynczo w sesji interaktywnej, może wysłać najwyżej 180 faktur na godzinę z jednego adresu IP w jednym kontekście NIP. Tyle wynosi domyślny limit z dokumentacji API KSeF 2.0. Przy wyprzedaży czy zbiorczym fakturowaniu na koniec miesiąca łatwo go przekroczyć, a wtedy każda kolejna próba kończy się odpowiedzią 429 Too Many Requests i blokadą, która wydłuża się z każdym kolejnym przekroczeniem.

Jak KSeF liczy limity żądań

• Para kontekst i adres IP: limity liczone są osobno dla każdej pary. Biuro rachunkowe i sam klient, łączący się z różnych IP w tym samym NIP-ie, mają osobne pule.
• Okno przesuwne: KSeF liczy żądania z ostatniej sekundy, ostatnich 60 sekund i ostatnich 60 minut. Okna nie zerują się o pełnej godzinie.
• Trzy progi naraz: blokada zaczyna się przy pierwszym przekroczeniu któregokolwiek z progów req/s, req/min albo req/h.

Domyślne limity dla najważniejszych operacji

Pozostałe operacje mają domyślnie 10 żądań na sekundę, 30 na minutę i 120 na godzinę. Limity mogą się zmieniać, bo Ministerstwo Finansów dostraja je do rzeczywistego ruchu. W godzinach 20:00–06:00 obowiązują wyższe limity pobierania niż w dzień.

Co oznacza Retry-After w odpowiedzi 429

Odpowiedź 429 zawiera nagłówek Retry-After z liczbą sekund, po których można spróbować ponownie, oraz opis, który limit został przekroczony. Czas blokady jest dynamiczny: rośnie przy powtarzających się przekroczeniach. Integracja, która ignoruje Retry-After i ponawia od razu, sama wydłuża sobie blokadę. Dokumentacja ostrzega też, że rozkładanie ruchu na wiele adresów IP w jednym kontekście może zostać uznane za próbę obejścia limitów i skończyć się blokadą dostępu do API.

Sesja interaktywna czy wsadowa

Sesja interaktywna wysyła faktury jedna po drugiej i pasuje do bieżącej sprzedaży w małym i średnim sklepie. Sesja wsadowa przesyła paczkę (do 10 000 faktur w sesji), więc przy zbiorczym fakturowaniu zużywa ułamek limitu żądań. Jeśli regularnie widzisz 429, to sygnał, że czas na wysyłkę wsadową, a nie na szybsze ponawianie.

Testowanie limitów przed startem

Na środowisku testowym limity są dziesięciokrotnie wyższe niż na produkcji, ale można włączyć limity produkcyjne osobnym endpointem. Środowisko DEMO ma limity takie jak produkcja. Warto przetestować wyprzedaż na DEMO, zanim zrobią to klienci. Więcej w tekście o środowisku testowym KSeF, a pozostałe kody błędów zebrałem w przeglądzie błędów KSeF.

Jak policzyć, czy sklep zmieści się w limicie

Weź liczbę faktur z najgorszej godziny w roku, a nie średnią dzienną. Sklep, który wystawia 1 000 faktur dziennie, ale 400 z nich w godzinę po starcie wyprzedaży, przekroczy limit 180 faktur na godzinę w sesji interaktywnej, choć średnio mieści się z zapasem. Do tego dochodzą żądania o status faktur i otwarcia sesji, które też zużywają limity. Jeśli w szczycie potrzebujesz więcej niż połowy limitu, zaplanuj kolejkę z tempem albo sesję wsadową od razu.

Źródło: limity żądań API w dokumentacji KSeF 2.0.