Komunikat „osiągnąłeś limit zapytań” w KSeF – portal i API

Jedno zjawisko, dwa interfejsy

W Aplikacji Podatnika zobaczysz komunikat tekstowy o limicie zapytań. W API ten sam mechanizm zwykle objawia się kodem HTTP 429 (Too Many Requests). W obu przypadkach oznacza to, że w krótkim czasie wykonano więcej operacji, niż dopuszcza mechanizm ochrony systemu przed przeciążeniem.

Co robić w portalu

• Nie odświeżaj strony wielokrotnie – każde odświeżenie to kolejne żądanie.
• Odczekaj od kilkudziesięciu sekund do kilku minut i spróbuj ponownie.
• Rozłóż w czasie wyszukiwania i eksporty danych, zwłaszcza w godzinach większego obciążenia.
• Jeśli to możliwe, spróbuj innej metody logowania (np. Profil Zaufany, podpis kwalifikowany) – czasem problem dotyczy konkretnej ścieżki logowania.

Jeżeli komunikat pojawia się już przy pierwszej próbie, warto sprawdzić komunikaty Ministerstwa Finansów o utrudnieniach – może to oznaczać ogólne przeciążenie systemu.

Co robić w API

1. Obsłuż kod HTTP 429 w swoim kliencie – odczytaj nagłówek Retry-After, odczekaj wskazany czas i ponów żądanie.
2. Zastosuj rosnące odstępy między próbami (tzw. backoff wykładniczy) – przy kolejnych błędach wydłużaj czas oczekiwania.
3. Ogranicz częstotliwość wywołań (np. synchronizacji danych czy pobierania faktur) – patrz Limity zapytań do API KSeF.
4. Tam, gdzie to możliwe, korzystaj z operacji zbiorczych (np. eksport paczek danych) zamiast wielu pojedynczych zapytań.

Jak tego nie mylić z błędem uprawnień

Kody 401 i 403 dotyczą zwykle uwierzytelnienia lub uprawnień, a nie liczby zapytań. Po ustąpieniu limitu warto wrócić do sprawdzenia uprawnień i kontekstu: Błąd 401 – uprawnienia, token, kontekst.