KSeF API rate limiting – limity wywołań API
Rate limiting w KSeF API 2.0
KSeF API 2.0 wprowadza precyzyjny mechanizm rate limiting z limitami liczby żądań w zadanych przedziałach czasowych: na sekundę, minutę, godzinę. Limity są publicznie udostępniane i zróżnicowane w zależności od środowiska (testowe, demo, produkcja) oraz charakteru operacji.
KSeF API nie zwraca nagłówków informujących z wyprzedzeniem o pozostałym limicie (brak nagłówków typu X-RateLimit-Remaining). Aktualne limity można sprawdzić przez dedykowane endpointy GET /limits/context (limity dla bieżącego kontekstu/sesji) oraz GET /rate-limits (aktualnie obowiązujące limity API). Przekroczenie limitu powoduje błąd 429 (Too Many Requests) z nagłówkiem Retry-After wskazującym czas oczekiwania w sekundach.
Wdrożenie odpowiedniej strategii obsługi rate limiting jest kluczowe dla stabilnej pracy integracji. Aplikacje powinny sprawdzać limity przez GET /limits/context lub GET /rate-limits, obsługiwać błąd 429 z nagłówkiem Retry-After i implementować retry z backoffem.
Instrukcja krok po kroku
1. Sprawdzanie aktualnych limitów
Sprawdzanie aktualnych limitów przez dedykowane endpointy: GET /limits/context (limity dla bieżącego kontekstu/sesji) oraz GET /rate-limits (aktualnie obowiązujące limity API w podziale na typ operacji). KSeF API nie zwraca nagłówków typu X-RateLimit-Remaining w każdej odpowiedzi.
2. Monitorowanie wykorzystania limitów
Monitorowanie wykorzystania limitów poprzez okresowe zapytania do GET /limits/context oraz GET /rate-limits. Dostosowanie częstotliwości żądań, gdy limity są bliskie wyczerpania, na podstawie zwracanych wartości limitów per sekunda/minuta/godzina.
3. Obsługa błędu 429
Obsługa błędu 429 (Too Many Requests) przy przekroczeniu limitów. Implementacja retry z wykładniczym backoffem: poczekaj przed ponownym żądaniem, zwiększ czas oczekiwania przy kolejnych próbach, sprawdź nagłówek Retry-After (jeśli dostępny) dla sugerowanego czasu oczekiwania.
4. Optymalizacja częstotliwości żądań
Optymalizacja częstotliwości żądań, aby uniknąć przekroczenia limitów: rozkładanie wysyłki wsadowej w czasie, używanie sesji wsadowych dla większych wolumenów, monitorowanie nagłówków limitów i dostosowanie tempa żądań. Implementacja kolejkowania żądań z priorytetami.
Najczęstsze problemy i rozwiązania
Błąd 429 Too Many Requests
Błąd 429 oznacza przekroczenie limitów rate limiting. Poczekaj przed ponownym żądaniem, sprawdź nagłówek Retry-After (jeśli dostępny) dla sugerowanego czasu oczekiwania, zaimplementuj retry z wykładniczym backoffem. Dostosuj częstotliwość żądań, aby uniknąć przekroczenia limitów w przyszłości.
Różne limity dla różnych operacji
Limity rate limiting mogą się różnić w zależności od typu operacji (uwierzytelnianie, wysyłka faktur, pobieranie danych). Sprawdź dokumentację API dotyczącą limitów dla konkretnych operacji. Monitorowanie nagłówków odpowiedzi pozwala na dostosowanie częstotliwości żądań dla różnych typów operacji.
Limity w środowisku testowym vs produkcja
Limity są zróżnicowane w zależności od środowiska: środowisko testowe ma niższe limity niż produkcja, środowisko demo ma limity pośrednie. Sprawdź dokumentację API dotyczącą limitów dla konkretnego środowiska. Przetestuj integrację w środowisku testowym, aby zrozumieć limity przed przejściem na produkcję.
Jak optymalizować wysyłkę wsadową?
Rozkładaj wysyłkę wsadową w czasie, aby uniknąć przekroczenia limitów. Używaj sesji wsadowych dla większych wolumenów, monitoruj nagłówki limitów i dostosuj tempo wysyłki. Implementuj kolejkowanie żądań z priorytetami i retry z backoffem przy błędach 429.
Sprawdzanie limitów przez API
KSeF API nie zwraca w każdej odpowiedzi nagłówków informujących o pozostałym limicie. Aktualne limity można sprawdzić przez GET /limits/context (limity dla bieżącego kontekstu/sesji, np. liczba dozwolonych sesji), GET /limits/subject (limity certyfikatów dla bieżącego podmiotu) oraz GET /rate-limits (aktualnie obowiązujące limity API w podziale na typ operacji: żądań na sekundę, minutę, godzinę). Jedynym nagłówkiem związanym z limitowaniem, zwracanym w odpowiedzi błędu 429, jest Retry-After.
Limity w różnych środowiskach
Limity są zróżnicowane w zależności od środowiska: środowisko testowe ma niższe limity (dla testowania i rozwoju), środowisko demo ma limity pośrednie (dla demonstracji), środowisko produkcja ma wyższe limity (dla rzeczywistego użycia). Limity mogą się również różnić w zależności od typu operacji. Sprawdź dokumentację API dla konkretnych limitów.
Strategie obsługi rate limiting
Strategie obsługi: okresowe sprawdzanie limitów przez GET /limits/context i GET /rate-limits, dostosowanie częstotliwości żądań, gdy limity są bliskie wyczerpania, implementacja retry z wykładniczym backoffem przy błędach 429, sprawdzanie nagłówka Retry-After dla dokładnego czasu oczekiwania, optymalizacja wysyłki wsadowej (rozkładanie w czasie).
Błąd 429 Too Many Requests
Błąd 429 jest zwracany przy przekroczeniu limitów rate limiting. Odpowiedź może zawierać nagłówek Retry-After z sugerowanym czasem oczekiwania przed ponownym żądaniem. Implementuj retry z wykładniczym backoffem: poczekaj przed ponownym żądaniem, zwiększ czas oczekiwania przy kolejnych próbach, sprawdź Retry-After dla sugerowanego czasu. Dostosuj częstotliwość żądań, aby uniknąć przekroczenia limitów w przyszłości.
FAQ
Jak działają limity rate limiting w KSeF API?
KSeF API 2.0 stosuje mechanizm rate limiting z limitami na sekundę, minutę i godzinę. Limity są różne dla środowisk testowych, demo i produkcji oraz zależą od typu operacji. Aktualne limity można sprawdzić przez GET /limits/context oraz GET /rate-limits. Przekroczenie limitów powoduje błąd 429 z nagłówkiem Retry-After.
Jak sprawdzić aktualne limity?
KSeF API nie zwraca informacji o limitach w nagłówkach każdej odpowiedzi. Aktualne limity sprawdza się przez dedykowane endpointy: GET /limits/context (limity dla bieżącego kontekstu/sesji), GET /limits/subject (limity certyfikatów dla podmiotu) i GET /rate-limits (aktualnie obowiązujące limity API per typ operacji). Okresowe odpytywanie tych endpointów pozwala na dostosowanie częstotliwości żądań i uniknięcie przekroczenia limitów.
Co zrobić przy błędzie 429?
Błąd 429 oznacza przekroczenie limitów rate limiting. Poczekaj przed ponownym żądaniem, sprawdź nagłówek Retry-After (jeśli dostępny) dla sugerowanego czasu oczekiwania, zaimplementuj retry z wykładniczym backoffem. Dostosuj częstotliwość żądań, aby uniknąć przekroczenia limitów w przyszłości.
Czy limity są różne dla różnych operacji?
Tak, limity rate limiting różnią się w zależności od typu operacji (uwierzytelnianie, wysyłka faktur, pobieranie danych, eksport paczek). Szczegółowy podział limitów per operacja zwraca endpoint GET /rate-limits. Monitorowanie tych wartości pozwala na dostosowanie częstotliwości żądań dla różnych typów operacji.
Jak optymalizować wysyłkę wsadową pod kątem limitów?
Rozkładaj wysyłkę wsadową w czasie, aby uniknąć przekroczenia limitów. Używaj sesji wsadowych dla większych wolumenów, sprawdzaj limity przez GET /limits/context i GET /rate-limits, dostosuj tempo wysyłki. Implementuj kolejkowanie żądań z priorytetami i retry z backoffem przy błędach 429.
Powiązane tematy
Przydatne serwisy
Status i komunikaty
API i narzędzia
Pierwsza grupa – status systemu KSeF i komunikaty techniczne Ministerstwa Finansów, druga – narzędzia do integracji z KSeF i walidacji faktur.