REST-klijent u Delphi: robustan prema timeoutima, retry-ima i 429 rate-limitima uz backoff

Ein REST-Aufruf ist in der Theorie simpel: Request raus, Response rein, fertig. In der Praxis scheitern produktive Integrationen aber selten an „falscher URL“, sondern an Randfällen im Betrieb: sporadische Timeouts, kurzzeitige DNS- oder TLS-Probleme, überlastete Downstream-Systeme, oder 429 (Too Many Requests), weil ein API-Gateway drosselt. Genau hier trennt sich ein Demo-Prototyp von einer dauerhaft betreibbaren Integration.

Dieser Beitrag zeigt, wie du mit dem RESTClient in Delphi robuste Kommunikationspfade etablierst: klare Timeout-Definitionen, gezielte Retries nur dort, wo sie fachlich und technisch sicher sind, und ein Backoff-Verhalten, das Rate-Limits respektiert statt sie zu verschärfen. Der Fokus liegt nicht auf „schönem Code“, sondern auf Verhalten unter Last, Debugging-Fähigkeit, sauberer Fehlerklassifikation und der Frage, wann sich der zusätzliche Aufwand wirklich lohnt.

Warum Timeouts, Retries und 429 in echten Umgebungen zusammen auftreten

In Unternehmensnetzen laufen REST-Calls selten „direkt ins Internet“. Typisch sind Proxy-Ketten, TLS-Terminierung, API-Gateways, WAFs (Web Application Firewall) und mehrere interne Hops. Jedes Glied kann eigene Timeouts und Limits haben. Ein Timeout auf Clientseite kann bedeuten:

• Der Server hat nicht geantwortet (Überlast, Deadlock, Downstream hängt).
• Die Antwort kam, aber zu spät (schlechter Pfad, Paketverlust, Congestion).
• Du hast dich selbst ausgesperrt: zu kurze Timeouts oder blockierender UI-/Main-Thread.

Parallel dazu führen „naive“ Retries häufig zu mehr Problemen: Wenn ein Server schon am Limit ist, erhöhen Retries die Last und machen aus einem kleinen Engpass eine Störung. Bei 429 ist das noch offensichtlicher: Ein Rate-Limit ist eine explizite Aufforderung, weniger zu senden oder später wiederzukommen. Ein Client ohne Backoff verhält sich wie ein DoS-Generator, nur unbeabsichtigt.

Robustheit entsteht daher nicht durch „Retry überall“, sondern durch ein konsistentes Entscheidungsmodell: Welche Fehler sind transient (vorübergehend), welche sind permanent, welche Requests sind retrybar (idempotent), und wie steuerst du die Wartezeiten so, dass dein System stabil bleibt.

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

Ein häufiger Stolperstein: „Timeout“ ist nicht gleich Timeout. Je nach Stack gibt es unterschiedliche Phasen. Auch wenn Delphi-REST-Komponenten vieles kapseln, solltest du das Modell im Kopf haben:

• Connect-Timeout: Zeit bis die TCP-Verbindung steht (inklusive DNS/TLS je nach Implementierung).
• Read/Response-Timeout: Zeit bis Bytes vom Server kommen oder die Antwort vollständig ist.
• Gesamt-Timeout: Obergrenze für den gesamten Call inklusive Retries.

In der Praxis ist ein zu kurzer Timeout mindestens genauso gefährlich wie ein zu langer: Du erzeugst künstliche Fehler, die dann retried werden und so Last erzeugen. Umgekehrt blockiert ein zu langer Timeout Worker-Threads, Queue-Slots oder UI-Reaktionsfähigkeit. Für Betrieb und Administration ist wichtig, dass Timeouts konfigurierbar sind (npr. pro Endpoint) und dass sie im Log mitgeschrieben werden.

Empfehlung aus der Praxis: Zwei Ebenen statt einer Zahl

Für REST-Calls in Business-Software haben sich zwei Ebenen bewährt:

• Call-Timeout (pro Request): realistische Obergrenze, die zum Use Case passt.
• Vremensko ograničenje zadatka (nadređeno): ako imaš batch obradu ili sinhronizacijski posao, ograniči ukupno vrijeme izvršavanja i uredno prekini.

Tako sprječavaš da pojedinačan API-odgovor čeka beskonačno, a istovremeno da noćni posao zbog mnogo ponovnih pokušaja „radi do podne“.

Pravilno odlučivanje o retryjima: ne tehnički, već prema poslovnim pravilima

Da li je retry dozvoljen nije isključivo tehničko pitanje. Ključni pojam je idempotentnost: Request je idempotentan ako višestruko izvršavanje ima isti efekt kao jedno izvršavanje. Tipični primjeri: GET je idempotentan, PUT često također (ako ciljnu resurs postaviš kompletno), DELETE obično također. POST je često ne-idempotentan (npr. „kreiraj novi nalog/auftrag“).

Zašto je to presudno? Timeout može značiti da je server ipak obradio request, ali odgovor nije stigao do klijenta. Ako potom bez provjere ponovo izvedete POST, stvaraš duplikate. To je u produkciji klasična „ghost“-greška: u aplikaciji piše „Timeout“, a u backendu postoje duplikati zapisa.

Sigurna osnova: retry samo za operacije koje su jasno pogodne za ponovni pokušaj

Robusno pravilo koje se pokazalo u integracijama:

• GET: pogodan za ponovni pokušaj kod tranzijentnih grešaka.
• PUT/DELETE: pogodan za ponovni pokušaj ako tvoja API to funkcionalno jasno definiše (npr. ID resursa je stabilan) i server ispravno implementira idempotentnost.
• POST: samo pogodan za ponovni pokušaj ako imaš strategiju Idempotency-Key (poslovno jedinstveni ID requesta koji server koristi za sprečavanje duplikata) ili ako je POST semantički idempotentan (rijetko, ali moguće).

Ako ne kontrolišeš API, tu moraš kao tehnički lead donijeti odluku: ili prihvatiš „bez retryja za POST“ (i za to izgradiš bolje greške/Resync-mehanizme), ili ugovoriš s dobavljačem API-ja Idempotency-Key ili model koji omogućava deduplikaciju.

429 Too Many Requests: poštuj rate-limite umjesto „bezrazložnog ponovnog pokušaja“

HTTP 429 nije „iritirajuća greška“, već mehanizam upravljanja. U enterprise okruženjima 429 često dolazi od:

• API-gatewaya s Token-Bucket/Leaky-Bucket ograničenjima (rate limiting).
• Cloud-API-ja s tenant-limitima po minuti/satu.
• Internih servisa koji se štite od vrhova opterećenja.

Za klijenta to znači: Retries da, ali kontrolisano. Bitne su dvije stvari:

• Izvuci i poštuj Retry-After-header, ako postoji (sekunde ili HTTP-datum).
• Koristi Backoff ako nema Retry-After ili dodatno uvedi jitter.

Najčešća zamka: 429 se tretira kao 500 („Server greška, odmah retry“). Time samo pojačavaš throttling. Bolje je: 429 je signal da se aktivno čeka i eventualno smanji paralelizam.

Backoff mit Jitter: warum ohne Zufall alles synchron kollabiert

Exponential Backoff bedeutet, dass du die Wartezeit nach jedem Fehlversuch erhöhst (z. B. 200 ms, 400 ms, 800 ms …). Jitter je nasumični dodatak koji sprečava da mnogi klijenti istovremeno opet zakucaju. Bez Jittera se u praksi često desi sljedeće: neko ograničenje se aktivira, 50 klijenata dobiju 429, svi čekaju tačno 1 sekundu i onda ponovo šalju istovremeno. Rezultat: opet 429 i imaš „Thundering Herd“-problem.

Praksi primjenjiv pristup su „Full Jitter“ ili „Equal Jitter“: izračunaš Backoff-prozor i zatim izabereš nasumično vrijeme čekanja unutar tog prozora. To zvuči kao detalj, ali u radu pravi razliku između stabilnog oporavka i stalnog šuma.

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

Wenn du Retries/Backoff „ad hoc“ an jeder Callsite einbaust, entsteht schnell inkonsistentes Verhalten: ein Endpoint retried aggressiv, ein anderer gar nicht, Logging ist lückenhaft, und die Admins sehen nur „sporadische Fehler“. Robust wird es, wenn du einen zentralen Aufrufpfad definierst:

• Ein Wrapper um RESTClient/RESTRequest, der Policy (Timeout, Retry, Backoff) anwendet.
• Ein ujednačen objekt rezultata: statusni kod, trajanje, brojač pokušaja, po potrebi zadnja Exception.
• Standardisiertes Logging (Request-ID/Correlation-ID, Endpoint, HTTP-Methode, relevante Header).

Das ist der Punkt, an dem sich zusätzlicher Code wirklich lohnt: Du bekommst reproduzierbares Verhalten, bessere Logs, und du kannst Policies pro Zielsystem konfigurieren, ohne die Anwendung umzubauen.

Policy-Entscheidungsmatrix (kurz und praktisch)

Für die meisten Integrationen reicht eine einfache Matrix, die du im Wrapper abbildest:

• Retry bei: Netzwerkfehler/Verbindungsabbrüche, 408, 429, 502, 503, 504 (je nach API-Vertrag).
• Kein Retry bei: 400/401/403/404 (meist Konfiguration/Authentifizierung/Request-Fehler), 409/422 (fachliche Konflikte/Validierung), sowie bei POST ohne Idempotency-Key.
• Max. Versuche: klein halten (oft 2–4 Versuche genügen), dafür besseres Monitoring.
• Max. Backoff: begrenzen (z. B. wenige Sekunden bis eine Minute), sonst blockierst du zu viele Worker.

Wichtig: Diese Regeln sind nicht universell. 404 kann bei „eventual consistency“ durchaus transient sein, 409 kann bei Locking-Strategien transient sein. Der Unterschied ist: Dann wird es eine bewusste Abweichung, nicht zufälliges Verhalten.

Konkreter Randfall: Timeout nach POST – war es jetzt gespeichert oder nicht?

Ovo je klasik koji se rijetko čisto reproducira u debuggeru: pošalješ POST (npr. „kreiranje tiketa“), tvoj klijent dobije Read-Timeout, i korisnik klikne „još jednom“. U Backend-u tiket već postoji. Bez kontramjere nastaju duplikati ili nedosljednosti.

Robustno je to samo uz jednu od tri strategije:

• Idempotency-Key: Generišeš za svaki funkcionalni postupak jedinstveni Request-ID (npr. GUID), šalješ ga kao header, i server garantuje deduplikovanu obradu.
• Client-seitige Deduplizierung: Čuvaš „pending requests“ lokalno sa vlastitim ID-jem i nakon timeouta radiš provjeru statusa (npr. GET po funkcionalnom ključu). To je zahtjevnije i nije uvijek moguće.
• Kein Retry: Jasno prijaviš da je status nepoznat i uvedeš manuelni/automatski resync-proces (npr. kasniji usklađeni pregled).

Ako gradiš integracije za operacije, „Status unbekannt“ je validna kategorija. Ne pokušavaj neizvjesnost ukloniti kodiranjem. Zabilježi je u logu, učini je vidljivom i osiguraj put za usklađivanje.

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

Backoff nije samo „Sleep“. Moraš ga postaviti u kontekst svoje aplikacije:

• Parallelität: Ako imaš 20 nitova i svi čekaju, 20 nitova je blokirano. Za servise je to često prihvatljivo, za desktop-aplikacije obično nije.
• Cancel: Korisnik prekida, servis se zaustavlja, posao se završava. Backoff-čekanje mora biti otkazivo, inače stop/shutdown procesi zapnu.
• Fairness: Više endpointa ne bi smjelo jedan drugog „izgladnjivati“. Rate-Limits su često po tokenu ili po endpointu; tvoj wrapper bi trebao moći upravljati po ciljanom sistemu.

Pristojan pristup je: implementirati Backoff u funkciji koja čeka u malim intervalima i pri tome provjerava Cancel-flag (npr. Event/Token). To nije luksuz: upravo ta tačka odlučuje hoće li Windows- i Linux-Services ispravno stati ili u konzoli Service Control Manager „zaglaviti“.

Maximaldauer und „Budget“ pro Call

Robustna retry-implementacija ne radi samo s „max tries“, već i s vremenskim budžetom. Na primjer: dozvoliš maksimalno 10 sekundi ukupnog vremena za poziv uključujući retrije. Tada pojedinačni pokušaj ne može iznenada blokirati 30 sekundi samo zato što je timeout pogrešno postavljen. Za administratore i operativu to je izuzetno vrijedno, jer ograničava vrhove latencije i stabilizira redove čekanja.

Debugging und Betriebsdiagnose: Ohne gute Logs sind Retries unsichtbare Fehlerverstärker

Retries bez logovanja su opasni, jer na kraju čuješ samo „ponekad traje“. Ako želiš postati otporan, trebaš logove koji ne samo da ispisuju izuzetke, već daju kontekst:

• Correlation-ID: jedinstveni ID zahtjeva koji generišeš po pozivu i zadržavaš pri svakom retryju.
• Broj pokušaja i Kašnjenje (Backoff).
• HTTP-Status i odabrani headeri (posebno Retry-After, RateLimit-Header falls vorhanden).
• Trajanje po pokušaju i ukupno vrijeme.
• Endpoint (Host + putanja), ali bez osjetljivih podataka u logu (Tokens, osobni podaci).

Za tehničke leadove je to također poluga za podešavanje granica: vidiš da li timeouti „uvijek pri 3 sekunde“ nastaju (vjerojatno prekratko) ili da li se 429 pojavljuje u talasima (prevelika paralelnost, preslab backoff ili nedostatak klijentskih rate-limitova).

Tipične zamke pri logovanju

• Preveliki payload: kompletno logovanje JSON tijela djeluje korisno, ali eksplodira kod fajlova/priloga i stvara probleme sa zaštitom podataka. Bolje: hash/veličina, Content-Type, i po potrebi ciljani debug-logging putem Feature-Flag.
• Nema razlike između Timeout i Cancel: prekinuti poziv nije greška u istom smislu kao timeout. Razdvoji ih, inače administratori prate fantomske greške.
• Retry prekriva prvobitni uzrok: ako pokušaj 1 ima TLS grešku, a pokušaj 2 uspije, i dalje želiš znati da je postojao kratkotrajni TLS-problem. To je rani znak upozorenja.

Klijentsko Rate-Limiting: Kada moraš sam upravljati opterećenjem

429 je odgovor servera. U mnogim scenarijima je ipak smisleno već na klijentskoj strani ograničiti promet, prije nego što uopće proizvedeš 429. To je naročito relevantno kada:

• imaš batch-jobove (npr. sinhronizacija podataka noću) i API dozvoljava samo X zahtjeva po minuti.
• koristiš više workera/threads i šalješ zahtjeve paralelno.
• imaš više instanci procesa (npr. terminal server ili više servisa).

U praksi to znači: implementiraš mali rate-limiter (npr. Token-Bucket) po ciljnom sistemu ili po API-Key. To smanjuje 429, stabilizira protok i čini vremena izvršavanja bolje planiranim. Za operacije i planiranje kapaciteta često je to vrijednije od „još jednog retryja“.

Važno: Rate-Limiter i Backoff se nadopunjuju

Rate-Limiter te u normalnom radu drži ispod limita. Backoff je reakcija kada ipak dobiješ 429 ili privremeno preopterećenje. Ko ima samo Backoff, stalno „vozi u zid“ i na kraju koči. Ko ima samo Rate-Limiter, loše reagira na iznenadne limite ili zajedničke kvote (npr. kada više sistema koristi isti API-Key).

Sigurnost i usklađenost: Retries ne smiju prikrivati probleme s autentifikacijom

U kompanijama su autentifikacija i autorizacija često najčešći „bug“ nakon deploy-anja: istekli tokeni, pogrešno konfigurirani client-credentials, nedostajuće proxy-iznimke. Retries tu ne pomažu i mogu biti štetni jer pune logove i triggeraju mehanizme zaključavanja (npr. account-locks, rate-limite na auth-endpointe).

Praktično pravilo: 401/403 nikada ne retryati (osim ako imaš namjerno Token-Refresh-handling). Ako implementiraš Token-Refresh, jasno ga odvoji od retry-mehanizma: prvo obnovi token, pa onda jednom ponovo pošalji. I zabilježi eksplicitno da je došlo do refresh-a.

Kada se uložen napor isplati – a kada ne

Robustni Retries i Backoff nisu cilj sami po sebi. Posebno se isplate kad vrijedi barem jedna od sljedećih tačaka:

• Integracija je poslovno kritična (npr. prijem narudžbi, otprema, obračun).
• API je vanjski ili interno vođen samo „best effort“ i nemaš potpunu kontrolu.
• Imaš vrhove opterećenja (npr. prozori za job-e, mjesečno zatvaranje) i želiš stabilno proći.
• Pokrećeš kao Service/Daemon i mora biti moguće planirano i uredno zaustavljanje.

Manje se isplati ako imaš isključivo „Bestätigungs-GETs“ u UI i korisnik ionako ponovo klikne, ili ako radiš u internom, vrlo stabilnom okruženju bez kvota gdje su greške odmah vidljive. Čak i tada su uredni Timeouts i Logging gotovo uvijek smisleni.

Pragmatična kontrolna lista za produkcioni rad Delphi-REST klijenta

• Timeouts: konfigurisano po endpointu, realno postavljeno, definisan ukupni budžet.
• Retry-Policy: ovisno o HTTP-metodi i idempotnosti, ne univerzalno.
• 429-Handling: uzeti u obzir Retry-After, Backoff s Jitter-om, paziti na paralelnost.
• Abbruchpfad: čekanje u Backoff-u mora biti prekidivo (Service-Stop, User-Cancel).
• Logging: Correlation-ID, pokušaj, kašnjenje, trajanje, status i zaglavlja – bez tajni.
• Optional: klijentski Rate-Limiter za batch/parallelni rad.

Fazit: Robustheit ist ein Verhalten, kein Catch-all-Exception-Block

Sa RESTClient u Delphi brzo dobiješ funkcionalne REST pozive. Producentno robusno postaje tek kad svjesno definiraš Timeouts, osiguraš Retries na stručnoj razini (Idempotenz!), i poštuješ 429 Rate-Limits uz Backoff i Jitter. Kod za to nije složen, ali mora biti centraliziran, konfigurabilan i uredno nadziran. Tada se trud isplati: manje „sporadičnih“ ticket-a, bolja dijagnostika u radu i integracije koje ne posustaju ni pod opterećenjem.

Ako želiš takvu Retry-/Backoff-politiku uredno uvesti u postojeće Delphi aplikacije ili odgovarajuće dimenzionirati za novu integraciju: kontaktiraj nas.

Za ovu temu su također važni Delphi Restclient Timeout i Retry-Strategie Delphi. Članak razjašnjava te aspekte i pokazuje na šta treba obratiti pažnju u praksi.

Razgovarajte o projektu ili modernizacijskom zahvatu s Net-Base.