Retry strategia - co to jest? Definicja pojęcia KSeF
Co to jest retry strategia?
Retry strategia (strategia ponawiania) to mechanizm automatycznego ponawiania żądań API po błędach przejściowych. Retry pozwala na automatyczne ponowienie żądania po błędzie, zwiększając szanse na pomyślne wykonanie operacji.
W kontekście Krajowego Systemu e-Faktur (KSeF), retry strategia jest używana do obsługi błędów przejściowych: błędy 5xx (błędy serwera, przejściowe), błąd 429 (Too Many Requests, rate limiting), timeout (brak odpowiedzi w określonym czasie).
Wykładniczy backoff zwiększa czas oczekiwania między kolejnymi próbami, zmniejszając obciążenie systemu i zwiększając szanse na pomyślne wykonanie. Strategia retry powinna uwzględniać typ błędu, maksymalną liczbę prób i maksymalny czas oczekiwania.
Błędy wymagające retry
Błędy wymagające retry w KSeF API: błędy 5xx (500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable - błędy serwera, przejściowe), błąd 429 (Too Many Requests - rate limiting, przejściowy), timeout (brak odpowiedzi w określonym czasie). Błędy 4xx (z wyjątkiem 429) są błędami klienta i nie powinny być ponawiane - wymagają poprawki w kodzie lub danych.
Exponential backoff
Wykładniczy backoff zwiększa czas oczekiwania między kolejnymi próbami: pierwsza próba po 1 sekundzie, druga po 2 sekundach, trzecia po 4 sekundach, czwarta po 8 sekundach, itd. (lub inny wzór wykładniczy). Dodaj losowe opóźnienie (jitter), aby uniknąć thundering herd problem (wszystkie klienty retry w tym samym czasie). Ustaw maksymalny czas oczekiwania (np. 60 sekund) i maksymalną liczbę prób (np. 5 prób).
Nagłówek Retry-After
Nagłówek Retry-After w odpowiedzi błędu 429 zawiera sugerowany czas oczekiwania przed ponownym żądaniem. Retry-After może być w sekundach (liczba całkowita) lub jako data HTTP (RFC 7231). Użyj wartości z Retry-After zamiast obliczonego backoff, jeśli jest dostępna. Sprawdź nagłówek w każdej odpowiedzi błędu 429.
Najlepsze praktyki
Zaimplementuj retry tylko dla błędów przejściowych (5xx, 429, timeout), używaj exponential backoff z jitter, sprawdzaj nagłówek Retry-After dla błędu 429, ustaw maksymalną liczbę prób i maksymalny czas oczekiwania, loguj wszystkie próby retry, monitoruj częstotliwość retry, nie retry dla błędów 4xx (z wyjątkiem 429), idempotentne operacje są bezpieczne do retry.
FAQ
Które błędy wymagają retry w KSeF API?
Błędy wymagające retry: błędy 5xx (błędy serwera, przejściowe), błąd 429 (Too Many Requests, rate limiting), timeout (brak odpowiedzi). Błędy 4xx (z wyjątkiem 429) są błędami klienta i nie powinny być ponawiane - wymagają poprawki w kodzie lub danych.
Jak zaimplementować exponential backoff?
Zaimplementuj wykładniczy backoff: pierwsza próba po 1 sekundzie, druga po 2 sekundach, trzecia po 4 sekundach, itd. Dodaj losowe opóźnienie (jitter), aby uniknąć thundering herd problem. Ustaw maksymalny czas oczekiwania (np. 60 sekund) i maksymalną liczbę prób (np. 5 prób).
Jak obsłużyć nagłówek Retry-After?
Sprawdź nagłówek Retry-After w odpowiedzi błędu 429 (jeśli dostępny) dla sugerowanego czasu oczekiwania. Użyj wartości z Retry-After zamiast obliczonego backoff, jeśli jest dostępna. Retry-After może być w sekundach (liczba) lub jako data HTTP (RFC 7231).
Ile prób retry powinno być maksymalnie?
Zaleca się maksymalnie 5 prób retry z maksymalnym czasem oczekiwania 60 sekund. Po przekroczeniu limitów zgłoś błąd do użytkownika lub systemu monitoringu. Zbyt wiele prób może obciążać system i opóźniać wykrycie rzeczywistych problemów. Dostosuj limity do charakteru operacji i wymagań aplikacji.