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.
System zwraca informacje o limitach w nagłówkach odpowiedzi HTTP, co pozwala aplikacjom na monitorowanie wykorzystania limitów i dostosowanie częstotliwości żądań. Przekroczenie limitów powoduje błąd 429 (Too Many Requests).
Wdrożenie odpowiedniej strategii obsługi rate limiting jest kluczowe dla stabilnej pracy integracji. Aplikacje powinny odczytywać nagłówki limitów, monitorować wykorzystanie i implementować retry z backoffem przy błędach 429.
Instrukcja krok po kroku
1. Odczytywanie nagłówków limitów
Odczytywanie nagłówków odpowiedzi HTTP zawierających informacje o limitach: X-RateLimit-Limit (maksymalna liczba żądań), X-RateLimit-Remaining (pozostała liczba żądań), X-RateLimit-Reset (czas resetu limitu). Nagłówki są zwracane w każdej odpowiedzi API.
2. Monitorowanie wykorzystania limitów
Monitorowanie wykorzystania limitów na podstawie nagłówków odpowiedzi. Sprawdzanie wartości X-RateLimit-Remaining, aby określić, ile żądań pozostało w danym przedziale czasowym. Dostosowanie częstotliwości żądań, gdy limity są bliskie wyczerpania.
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.
Nagłówki rate limiting
System zwraca informacje o limitach w nagłówkach odpowiedzi HTTP: X-RateLimit-Limit (maksymalna liczba żądań w przedziale czasowym), X-RateLimit-Remaining (pozostała liczba żądań), X-RateLimit-Reset (czas resetu limitu w formacie Unix timestamp). Nagłówki są zwracane w każdej odpowiedzi API i pozwalają aplikacjom na monitorowanie wykorzystania limitów.
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: odczytywanie nagłówków limitów w każdej odpowiedzi, monitorowanie wykorzystania limitów (X-RateLimit-Remaining), 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 sugerowanego 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 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. System zwraca informacje o limitach w nagłówkach odpowiedzi HTTP (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset). Przekroczenie limitów powoduje błąd 429.
Jak odczytywać informacje o limitach?
System zwraca informacje o limitach w nagłówkach odpowiedzi HTTP: X-RateLimit-Limit (maksymalna liczba żądań), X-RateLimit-Remaining (pozostała liczba żądań), X-RateLimit-Reset (czas resetu limitu). Nagłówki są zwracane w każdej odpowiedzi API. Monitorowanie nagłówkó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 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.
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, monitoruj nagłówki limitów i dostosuj tempo wysyłki. Implementuj kolejkowanie żądań z priorytetami i retry z backoffem przy błędach 429. Sprawdź dokumentację API dla limitów dotyczących sesji wsadowych.