RESTKlient w Delphi: odporny na przekroczenia czasu oczekiwania, ponowne próby i limity 429 z mechanizmem backoff

Wywołanie REST jest w teorii proste: żądanie wychodzi, odpowiedź przychodzi, koniec. W praktyce jednak produktywne integracje rzadko zawodzą z powodu „nieprawidłowego URL”, lecz z powodu przypadków brzegowych w eksploatacji: sporadycznych Timeouts, krótkotrwałych problemów z DNS lub TLS, przeciążonych systemów downstream, albo 429 (Too Many Requests), gdy API-Gateway ogranicza przepustowość. Właśnie tutaj prototyp demonstracyjny różni się od integracji nadającej się do ciągłej eksploatacji.

Ten artykuł pokazuje, jak za pomocą RESTClient w Delphi ustanowić odporne ścieżki komunikacyjne: jasne definicje timeoutów, celowe ponawiania (retries) tylko tam, gdzie są fachowo i technicznie bezpieczne, oraz zachowanie typu backoff, które respektuje limity zamiast je zaostrzać. Skupienie nie leży na „ładnym kodzie”, lecz na zachowaniu pod obciążeniem, możliwościach debugowania, precyzyjnej klasyfikacji błędów oraz na pytaniu, kiedy dodatkowy wysiłek rzeczywiście ma sens.

Warum Timeouts, Retries und 429 in echten Umgebungen zusammen auftreten

W sieciach korporacyjnych wywołania REST rzadko idą „bezpośrednio do internetu”. Typowe są łańcuchy proxy, terminacja TLS, API‑Gateway, WAF (Web Application Firewall) i kilka wewnętrznych hopów. Każde ogniwo może mieć własne timeouty i limity. Timeout po stronie klienta może oznaczać:

• Serwer nie odpowiedział (przeciążenie, deadlock, zalegający komponent downstream).
• Odpowiedź dotarła, ale za późno (zła ścieżka, utrata pakietów, congestion).
• Sam się zablokowałeś: zbyt krótkie timeouty lub blokujący wątek UI / wątek główny.

Równocześnie „naiwne” retries często powodują więcej problemów: jeśli serwer już jest na granicy swoich zasobów, ponawiania zwiększają obciążenie i z małego wąskiego gardła robią poważną awarię. Przy 429 jest to jeszcze bardziej oczywiste: limit szybkości to wyraźne polecenie, by wysyłać mniej lub wrócić później. Klient bez mechanizmu backoff zachowuje się jak generator DoS — tylko niezamierzony.

Odporność nie powstaje więc przez „Retry wszędzie”, lecz przez spójny model decyzyjny: które błędy są przejściowe, które trwałe, które żądania są retryowalne (idempotentne), i jak kontrolujesz czasy oczekiwania, żeby system pozostał stabilny.

Timeouts sauber setzen: Was genau bedeutet „Timeout“ beim RESTClient in Delphi?

Częsta pułapka: „Timeout” nie jest jednoznaczny. W zależności od stosu występują różne fazy. Nawet jeśli komponenty Delphi-REST wiele kapsułują, warto mieć ten model w głowie:

• Connect-Timeout: czas do nawiązania połączenia TCP (włącznie z DNS/TLS, zależnie od implementacji).
• Read/Response-Timeout: czas do momentu otrzymania bajtów od serwera lub do pełnego zakończenia odpowiedzi.
• Gesamt-Timeout: górna granica dla całego wywołania, łącznie z ponowieniami.

W praktyce zbyt krótki timeout jest przynajmniej tak samo niebezpieczny jak zbyt długi: generujesz sztuczne błędy, które są potem ponawiane i w ten sposób nakładasz dodatkowe obciążenie. Z drugiej strony zbyt długi timeout blokuje wątki robocze, sloty w kolejkach lub reagowanie UI. Dla utrzymania i administracji ważne jest, aby timeouty były konfigurowalne (np. per endpoint) i żeby były zapisywane w logach.

Empfehlung aus der Praxis: Zwei Ebenen statt einer Zahl

Dla wywołań REST w oprogramowaniu biznesowym sprawdziły się dwie warstwy:

• Call-Timeout (pro Request): realistyczna górna granica dopasowana do przypadku użycia.
• Job-Timeout (nadrzędne): jeśli masz przetwarzanie wsadowe lub zadanie synchronizacji, ogranicz całkowity czas wykonania i zakończ je w sposób uporządkowany.

Dzięki temu zapobiegniesz sytuacji, w której pojedyncza odpowiedź API czeka wiecznie, oraz jednocześnie temu, by nocne zadanie z powodu wielu ponowień „działało do południa”.

Właściwe decyzje dotyczące ponowień: nie technicznie, lecz merytorycznie

To, czy ponowienie jest dozwolone, nie jest czysto techniczną kwestią. Kluczowym pojęciem jest idempotencja: żądanie jest idempotentne, jeśli jego wielokrotne wykonanie daje ten sam efekt co jednokrotne. Typowe przykłady: GET jest idempotentny, PUT często również (jeśli ustawiasz obiekt docelowy w całości), DELETE zwykle także. POST często nie jest idempotentny (np. „utworzenie nowego zlecenia”).

Dlaczego to ma znaczenie? Timeout może oznaczać, że serwer jednak przetworzył żądanie, ale odpowiedź nie dotarła do klienta. Jeśli następnie bezrefleksyjnie powtórzysz POST, wygenerujesz duplikaty. To klasyczny „błąd widmo” w eksploatacji: w aplikacji widzisz „Timeout”, a w backendzie są zdublowane rekordy.

Bezpieczna podstawa: ponawianie tylko dla jednoznacznie podlegających ponownemu wykonaniu operacji

Sprawdzona zasada, która dobrze działa w integracjach:

• GET: do ponowienia przy błędach przejściowych.
• PUT/DELETE: do ponowienia, jeśli Twoje API merytorycznie to jasno definiuje (np. identyfikator zasobu jest stabilny) i serwer prawidłowo zaimplementował idempotencję.
• POST: tylko do ponowienia, jeśli masz strategię z Idempotency-Key (merytorycznie unikalna ID żądania, która po stronie serwera zapobiega duplikatom) albo jeśli dany POST jest semantycznie idempotentny (rzadko, ale możliwe).

Jeśli nie kontrolujesz API, to moment, w którym jako lider techniczny musisz podjąć decyzję: albo akceptujesz „brak retry dla POST” (i w zamian budujesz lepsze komunikaty o błędach / mechanizmy ponownej synchronizacji), albo negocjujesz z dostawcą API wprowadzenie Idempotency-Key albo modelu zapobiegającego duplikacji.

429 Too Many Requests: respektuj limity zamiast „bezmyślnie ponawiać”

HTTP 429 to nie „irytujący komunikat o błędzie”, lecz mechanizm sterujący. W środowiskach korporacyjnych 429 często pochodzi z:

• API-Gateway z limitami Token-Bucket/Leaky-Bucket (Rate Limiting).
• Cloud-API z limitami na klienta na minutę/godzinę.
• usług wewnętrznych, które chronią się przed skokami obciążenia.

Dla klienta oznacza to: ponawianie tak, ale kontrolowane. Ważne są dwie rzeczy:

• Odczytać nagłówek Retry-After, jeśli jest dostępny (sekundy lub data HTTP).
• stosować backoff, gdy nie ma Retry-After lub gdy dodatkowo wprowadzasz jitter.

Najczęstsza pułapka: 429 jest traktowany jak 500 („błąd serwera, natychmiast ponów”). W ten sposób nasilasz dławienie. Lepiej: 429 to sygnał, by aktywnie czekać i w razie potrzeby zmniejszyć liczbę równoczesnych żądań.

Backoff z jitterem: dlaczego bez elementu losowego wszystko synchronicznie się załamuje

Exponential Backoff oznacza, że zwiększasz czas oczekiwania po każdej nieudanej próbie (np. 200 ms, 400 ms, 800 ms …). Jitter to losowy składnik, który zapobiega jednoczesnym ponownym zapytaniom wielu klientów. Bez jittera w praktyce często dzieje się następujące: wchodzi limit, 50 klientów dostaje 429, wszyscy czekają dokładnie 1 sekundę i wysyłają znów jednocześnie. Wynik: ponownie 429 i masz problem „Thundering Herd”.

Praktyczny podejście to „Full Jitter” lub „Equal Jitter”: obliczasz okno backoff i wybierasz losowy czas oczekiwania w jego obrębie. Brzmi jak szczegół, ale w eksploatacji decyduje o różnicy między stabilnym odzyskaniem a ciągłym przepychaniem się żądań.

Ein sauberes Muster: REST-Aufrufe kapseln, statt überall Retry-Schleifen zu verstreuen

Jeśli implementujesz retry/backoff „ad hoc” w każdej callsite, szybko powstaje niespójne zachowanie: jeden endpoint ponawia agresywnie, inny wcale, logowanie jest niekompletne, a administratorzy widzą tylko „sporadyczne błędy”. Staje się to solidne, gdy zdefiniujesz centralną ścieżkę wywołań:

• Wrapper wokół RESTClient/RESTRequest, który stosuje politykę (timeout, retry, backoff).
• Jednolity obiekt wyniku: kod statusu, czas trwania, licznik prób, ewentualnie ostatni wyjątek.
• Standaryzowane logowanie (Request-ID/Correlation-ID, endpoint, metoda HTTP, istotne nagłówki).

W tym miejscu dodatkowy kod naprawdę się opłaca: uzyskujesz odtwarzalne zachowanie, lepsze logi i możliwość konfigurowania polityk per system docelowy bez przebudowy aplikacji.

Policy-Entscheidungsmatrix (kurz und praktisch)

Dla większości integracji wystarczy prosta macierz, którą odwzorujesz w wrapperze:

• Ponawiać w przypadku: błędy sieci/zerwania połączeń, 408, 429, 502, 503, 504 (w zależności od umowy API).
• Nie ponawiać w przypadku: 400/401/403/404 (zwykle błąd konfiguracji/uwierzytelnienia/żądania), 409/422 (konflikty domenowe/walidacja), oraz przy POST bez Idempotency-Key.
• Maks. prób: utrzymuj nisko (często 2–4 próby wystarczą), za to lepszy monitoring.
• Maks. Backoff: ogranicz (np. kilka sekund do minuty), inaczej zablokujesz zbyt wiele workerów.

Ważne: te reguły nie są uniwersalne. 404 przy „eventual consistency” może być przejściowy, 409 przy strategiach blokowania też może być przejściowy. Różnica polega na tym, że wtedy jest to świadoma odstępstwo, a nie losowe zachowanie.

Konkretny przypadek brzegowy: timeout po POST – czy to zostało zapisane czy nie?

To klasyczny przypadek, który rzadko udaje się czysto odtworzyć w debuggerze: wysyłasz POST (np. „Utwórz zgłoszenie“), klient otrzymuje timeout odczytu, a użytkownik klika „jeszcze raz“. W backendzie zgłoszenie jednak już istnieje. Bez środków zaradczych powstają duplikaty lub niespójności.

Robustne rozwiązanie wymaga jednej z trzech strategii:

• Idempotency-Key: Dla każdej operacji biznesowej generujesz unikalne ID żądania (np. GUID), wysyłasz je jako nagłówek, a serwer gwarantuje przetwarzanie bez duplikatów.
• Deduplikacja po stronie klienta: Przechowujesz lokalnie „oczekujące żądania” z własnym ID i po przekroczeniu czasu wykonujesz sprawdzenie statusu (np. GET po kluczu biznesowym). To jest bardziej złożone i nie zawsze możliwe.
• Brak ponownej próby: Komunikujesz jasno, że status jest nieznany, i wdrażasz ręczny/automatyczny proces resynchronizacji (np. późniejszy wyrównawczy przegląd).

Jeśli budujesz integracje dla eksploatacji, „Status nieznany” to prawidłowa kategoria. Nie próbuj zakodować niepewności. Loguj ją, spraw, by była widoczna, i zapewnij ścieżkę do jej uzgodnienia.

Backoff-Design in der Praxis: Grenzwerte, Parallelität und Cancel

Backoff to nie tylko „usypianie“. Musisz osadzić go w kontekście swojej aplikacji:

• Równoległość: Jeśli masz 20 wątków i wszystkie czekają, 20 wątków jest zablokowanych. Dla usług to często jest akceptowalne, dla aplikacji desktopowych raczej nie.
• Anulowanie: Użytkownik przerywa, usługa zatrzymuje się, zadanie kończy się. Oczekiwanie w backoffie musi być przerywalne, inaczej procesy zatrzymywania/wyłączania będą blokowane.
• Sprawiedliwość: Kilka endpointów nie powinno się nawzajem „zagłodzić”. Limity przepustowości są często stosowane dla tokena lub dla endpointu; twój wrapper powinien móc sterować limitem dla każdego systemu docelowego.

Czyste podejście to: implementować backoff jako funkcję, która czeka w krótkich interwałach i przy tym sprawdza flagę anulowania (np. Event/Token). To nie jest luksus: właśnie ta część decyduje, czy Windows- i Linux-usługi zatrzymają się poprawnie, czy w konsoli Service Control Manager „zawisną”.

Maksymalny czas trwania i „budżet” na wywołanie

Odporna implementacja ponowień działa nie tylko z „maks. próbami”, ale także z budżetem czasowym. Przykład: zezwalasz na maksymalnie 10 sekund łącznego czasu dla wywołania łącznie z ponowieniami. Dzięki temu pojedyncza próba nie może nagle zablokować na 30 sekund tylko dlatego, że timeout został źle ustawiony. Dla administratorów i eksploatacji to bezcenna wartość, ponieważ ogranicza skoki latencji i stabilizuje kolejki.

Debugowanie i diagnostyka operacyjna: Bez dobrych logów ponowienia są niewidocznym wzmacniaczem błędów

Ponawiania bez logowania są niebezpieczne, ponieważ na końcu słyszysz tylko „czasami trwa”. Jeśli chcesz być odporny, potrzebujesz logów, które nie tylko rejestrują wyjątki, lecz dostarczają kontekst:

• Correlation-ID: identyfikator żądania generowany dla każdego wywołania i zachowywany przy każdym ponowieniu.
• Numer próby i opóźnienie (Backoff).
• Status HTTP i wybrane nagłówki (w szczególności Retry-After, nagłówki RateLimit jeśli obecne).
• Czas trwania każdej próby i łączny czas.
• Endpoint (host + ścieżka), ale bez danych wrażliwych w logu (tokeny, dane osobowe).

Dla technicznych liderów to też dźwignia do regulacji limitów: widzisz, czy timeouty „zawsze przy 3 sekundach” występują (prawdopodobnie za krótko) albo czy 429 pojawia się falami (zbyt wysoka równoległość, zbyt słaby Backoff lub brak limitów po stronie klienta).

Typowe pułapki logów

• Zbyt duży payload: logowanie całych ciał JSON wydaje się pomocne, ale eksploduje przy plikach/załącznikach i powoduje problemy z ochroną danych. Lepiej: hash/rozmiar, Content-Type oraz w razie potrzeby selektywne debug-logowanie za pomocą feature-flag.
• Brak rozróżnienia Timeout vs. Cancel: przerwane wywołanie nie jest błędem w tym samym sensie co timeout. Rozdziel je, inaczej administratorzy będą tropić błędy-fantomowe.
• Ponawianie tłumi pierwotną przyczynę: jeśli próba 1 ma błąd TLS, próba 2 kończy się sukcesem, chcesz mimo to wiedzieć, że pojawił się problem z TLS. To sygnał wczesnego ostrzegania.

Limitowanie po stronie klienta: Wenn du die Last selbst steuern musst

429 to odpowiedź serwera. W wielu scenariuszach sensowne jest jednak ograniczanie po stronie klienta zanim w ogóle wygenerujesz 429. Ma to szczególne znaczenie, gdy:

• masz zadania wsadowe (z. B. Datenabgleich nachts) i API pozwala tylko X żądań na minutę.
• używasz wielu workerów/wątków i wysyłasz żądania równolegle.
• masz wiele instancji procesu (z. B. Terminalserver oder mehrere Services).

W praktyce oznacza to: implementujesz niewielki Rate-Limiter (np. Token-Bucket) dla każdego systemu docelowego lub dla każdego API-Key. To redukuje 429, stabilizuje przepustowość i czyni czasy wykonywania lepiej przewidywalnymi. Dla operacji i planowania pojemności często to jest cenniejsze niż „noch ein Retry”.

Ważne: Rate-Limiter i Backoff się uzupełniają

Rate-Limiter trzyma cię w normalnym trybie poniżej limitu. Backoff to reakcja, gdy mimo to dostajesz 429 lub tymczasowe przeciążenie. Kto ma tylko Backoff, jedzie ciągle „gegen die Wand” i w rezultacie hamuje. Kto ma tylko Rate-Limiter, słabo reaguje na zaskakujące limity lub współdzielone kwoty (z. B. wenn mehrere Systeme denselben API-Key nutzen).

Bezpieczeństwo i zgodność: ponawiania nie mogą maskować problemów z uwierzytelnianiem

W przedsiębiorstwach uwierzytelnianie i autoryzacja są często najczęstszym „błędem” po wdrożeniu: wygasłe tokeny, błędnie skonfigurowane poświadczenia klienta, brak wyjątków proxy. Ponawiania tu nic nie pomogą, a mogą nawet zaszkodzić, bo zapełniają logi i uruchamiają mechanizmy blokujące (z. B. Account-Locks, Rate-Limits auf Auth-Endpunkten).

Praktyczna zasada: 401/403 nigdy nie ponawiać (außer du hast ein bewusstes Token-Refresh-Handling). Jeśli implementujesz odświeżanie tokena, oddziel to wyraźnie od mechanizmu ponawiania: najpierw odśwież token, potem wyślij ponownie raz. I zaloguj wyraźnie, że odświeżenie miało miejsce.

Kiedy wysiłek się opłaca — a kiedy nie

Solidne mechanizmy ponawiania i backoff nie są celem samym w sobie. Opłacają się szczególnie, gdy spełniony jest przynajmniej jeden z poniższych warunków:

• Integracja jest krytyczna dla biznesu (np. przyjmowanie zleceń, wysyłka, rozliczenia).
• API jest zewnętrzne lub obsługiwane wewnętrznie w modelu „best effort” i nie masz pełnej kontroli.
• Masz skoki obciążenia (np. okno zadań, zamknięcie miesiąca) i chcesz przejść przez nie stabilnie.
• Uruchamiasz to jako usługę/daemon i musisz mieć możliwość planowanego i czystego zatrzymania.

Mniej się to opłaca, gdy masz wyłącznie „potwierdzające żądania GET” w interfejsie użytkownika i użytkownik i tak ponownie klika, albo gdy działasz w wewnętrznym, bardzo stabilnym środowisku bez limitów i błędy są od razu widoczne. Nawet wtedy jednak sensowne są staranne timeouty i logowanie.

Pragmatyczna lista kontrolna dla produkcyjnej eksploatacji Delphi-RESTClient

• Timeouts: konfigurowalne per endpoint, realistycznie dobrane, zdefiniowany całkowity budżet czasowy.
• Retry-Policy: zależna od metody HTTP i idempotencji, nie stosować uniwersalnie.
• 429-Handling: uwzględniać Retry-After, backoff z jitterem, kontrolować równoległość.
• Abbruchpfad: oczekiwanie w backoff musi być przerywalne (zatrzymanie usługi, anulowanie przez użytkownika).
• Logging: Correlation-ID, próba, opóźnienie, czas trwania, status/headers – bez sekretów.
• Optional: po stronie klienta limiter (rate-limiter) dla pracy wsadowej/paralelnej.

Wniosek: odporność to zachowanie, a nie blok obsługujący wszystkie wyjątki

Z RESTClient w Delphi szybko uzyskasz działające wywołania REST. Prawdziwą odporność w produkcji osiągniesz jednak dopiero wtedy, gdy świadomie zdefiniujesz timeouty, zabezpieczysz ponawiania od strony domeny (idempotencja!), oraz będziesz respektować limity 429 stosując backoff i jitter. Kod do tego nie jest skomplikowany, ale musi być scentralizowany, konfigurowalny i dobrze obserwowalny. Wtedy nakład pracy się opłaca: mniej „sporadycznych” zgłoszeń, lepsza diagnostyka w eksploatacji i integracje, które nie zawodzą nawet pod obciążeniem.

Jeśli chcesz wprowadzić taką politykę ponawiania/backoff dla istniejących aplikacji Delphi albo odpowiednio dobrać ją do nowej integracji: skontaktuj się.

W tym kontekście ważne są również timeouty i strategia retry Restclienta Delphi. Artykuł porządkuje te aspekty w zrozumiały sposób i pokazuje, na czym to polega w codziennej pracy.

Omów projekt lub przedsięwzięcie modernizacyjne z Net-Base.