Rate limiting - co to jest? Definicja pojęcia KSeF
Co to jest rate limiting?
Rate limiting (ograniczanie przepustowości) to mechanizm kontroli dostępu do API, który ogranicza liczbę żądań, które mogą być wysłane w określonym przedziale czasowym. Rate limiting jest używany do ochrony systemu przed przeciążeniem, zapewnienia sprawiedliwego dostępu do zasobów oraz zapobiegania nadużyciom.
W kontekście Krajowego Systemu e-Faktur (KSeF), API 2.0 stosuje precyzyjny 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 (uwierzytelnianie, wysyłka faktur, pobieranie danych).
KSeF API nie zwraca w odpowiedziach nagłówków informujących z wyprzedzeniem o pozostałym limicie. Aktualne wartości limitów można sprawdzić przez dedykowane endpointy GET /limits/context i GET /limits/subject. Przekroczenie limitu powoduje błąd 429 (Too Many Requests) z nagłówkiem Retry-After wskazującym czas do kolejnej próby.
Rate limiting w KSeF API
KSeF API 2.0 stosuje precyzyjny mechanizm rate limiting z limitami na sekundę, minutę i godzinę. Limity są: różne dla środowisk (testowe, demo, produkcja), zależne od typu operacji (uwierzytelnianie, wysyłka faktur, pobieranie danych), publicznie udostępniane w dokumentacji API. Przekroczenie limitu powoduje błąd 429 z nagłówkiem Retry-After.
Sprawdzanie limitów
KSeF API nie zwraca nagłówków typu X-RateLimit-* w standardowych odpowiedziach. Aby sprawdzić aktualne limity, należy wywołać dedykowane endpointy: GET /limits/context (limity dla bieżącego kontekstu uwierzytelnienia) oraz GET /limits/subject (limity dla konkretnego podmiotu). Te endpointy pozwalają aplikacjom na świadome planowanie częstotliwości żądań i uniknięcie przekroczenia limitów.
Obsługa błędu 429
Błąd 429 (Too Many Requests) jest zwracany przy przekroczeniu limitów rate limiting. Odpowiedź może zawierać nagłówek Retry-After z sugerowanym czasem oczekiwania przed ponownym żądaniem. Strategie obsługi: 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.
FAQ
Jak działają limity rate limiting w KSeF API?
KSeF API 2.0 stosuje precyzyjny 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. Przekroczenie limitu powoduje błąd 429 z nagłówkiem Retry-After.
Jak sprawdzić aktualne limity w KSeF API?
KSeF API nie zwraca nagłówków typu X-RateLimit-* w odpowiedziach. Aktualne wartości limitów można sprawdzić przez dedykowane endpointy: GET /limits/context (limity dla bieżącego kontekstu uwierzytelnienia) oraz GET /limits/subject (limity dla konkretnego podmiotu).
Co zrobić przy błędzie 429?
Błąd 429 oznacza przekroczenie limitów rate limiting. Sprawdź nagłówek Retry-After w odpowiedzi - zawiera sugerowany czas oczekiwania przed ponownym żądaniem. 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 mogą się różnić w zależności od typu operacji (uwierzytelnianie, wysyłka faktur, pobieranie danych). Aktualne wartości limitów można sprawdzić przez endpointy GET /limits/context i GET /limits/subject.
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.