Jak zaimplementować retry strategię dla błędów przejściowych w KSeF API?

Zaimplementuj retry tylko dla błędów przejściowych (5xx, 429, timeout). Używaj exponential backoff z jitter: pierwsza próba po 1 sekundzie, druga po 2 sekundach, trzecia po 4 sekundach, itd. Sprawdzaj nagłówek Retry-After dla błędu 429. Ustaw maksymalną liczbę prób (np. 5) i maksymalny czas oczekiwania (np. 60 sekund). Loguj wszystkie próby retry i monitoruj częstotliwość.

KSeF API retry strategia – obsługa błędów przejściowych

Implementacja strategii retry z wykładniczym backoffem jest kluczowa dla obsługi błędów przejściowych w KSeF API. Błędy 5xx, 429 i timeout wymagają ponowienia żądania z odpowiednim opóźnieniem.

Strategie retry w KSeF API

Błędy przejściowe (5xx, 429, timeout) w KSeF API wymagają implementacji strategii retry z wykładniczym backoffem. Retry pozwala na automatyczne ponowienie żądania po błędzie, zwiększając szanse na pomyślne wykonanie operacji.

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.

Nie wszystkie błędy wymagają retry: błędy 4xx (z wyjątkiem 429) są błędami klienta i nie powinny być ponawiane, błędy 5xx i 429 są błędami przejściowymi i wymagają retry, timeout wymaga retry z backoffem.

Instrukcja krok po kroku

1. Identyfikacja błędów przejściowych

Zidentyfikuj błędy wymagające retry: błędy 5xx (błędy serwera, przejściowe), błąd 429 (Too Many Requests, rate limiting), timeout (brak odpowiedzi w określonym czasie). Błędy 4xx (z wyjątkiem 429) są błędami klienta i nie powinny być ponawiane.

2. Implementacja exponential backoff

Zaimplementuj wykładniczy backoff: pierwsza próba po 1 sekundzie, druga po 2 sekundach, trzecia po 4 sekundach, itd. (lub inny wzór wykładniczy). Ustaw maksymalny czas oczekiwania (np. 60 sekund) i maksymalną liczbę prób (np. 5 prób).

3. Obsługa nagłówka 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 lub jako data HTTP.

4. Logowanie i monitorowanie

Loguj wszystkie próby retry z informacjami o błędzie, liczbie próby, czasie oczekiwania i wyniku. Monitoruj częstotliwość retry, aby zidentyfikować problemy z integracją lub systemem KSeF. Alerty dla wysokiej częstotliwości retry mogą wskazywać na problemy.

Najczęstsze problemy i rozwiązania

Które błędy wymagają retry?

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?

Jak obsłużyć nagłówek Retry-After?

Maksymalna liczba prób retry

Ustaw maksymalną liczbę prób retry (np. 5 prób) i maksymalny czas oczekiwania (np. 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.

Błędy wymagające retry

Błędy wymagające retry: 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?

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?

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.

Czy wszystkie operacje są bezpieczne do retry?

Idempotentne operacje (GET, PUT, DELETE) są bezpieczne do retry. Operacje POST mogą nie być idempotentne, więc retry może spowodować duplikaty. Sprawdź dokumentację API dotyczącą idempotentności operacji. Dla operacji nieidempotentnych rozważ użycie idempotency keys lub sprawdzenie statusu przed retry.