RESTklijent u Delphi: Robustan prema timeoutima, ponovnim pokušajima i 429 ograničenjima brzine 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 (z. B. 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.
• Timeout zadatka (nadređeno): ako imaš batch-proces ili sync-job, ograniči ukupno vrijeme izvođenja i prekini uredno.

Tako sprječavaš da pojedinačni API-odgovor čeka zauvijek, i istovremeno da noćni posao zbog brojnih ponovnih pokušaja „radi do podne“.

Pravilno odlučivanje o ponovnim pokušajima: ne tehnički, nego funkcionalno

Je li ponovni pokušaj dozvoljen nije isključivo tehničko pitanje. Ključni pojam je idempotencija: zahtjev je idempotentan ako njegovo višestruko izvršavanje ima isti učinak kao jedno. Tipični primjeri: GET je idempotentan, PUT često također (ako ciljnu entitet u potpunosti postaviš), DELETE obično također. POST često nije idempotentan (npr. kreiranje novog naloga).

Zašto je to presudno? Timeout može značiti da je server zahtjev ipak obradio, ali odgovor nije stigao klijentu. Ako tada slijepo ponoviš POST, stvaraš duplikate. To je u produkciji klasičan nevidljivi problem: u aplikaciji stoji „Timeout“, a u backendu postoje duplicirani zapisi.

Sigurna osnova: ponovne pokušaje samo za jasno ponovljive operacije

Robusno pravilo koje se pokazalo u integracijama:

• GET: moguće ponavljati kod tranzijentnih pogrešaka.
• PUT/DELETE: moguće ponavljati ako tvoj API to funkcionalno jasno definira (npr. ID resursa je stabilan) i server ispravno implementira idempotenciju.
• POST: moguće ponavljati samo ako imaš strategiju Idempotency-Key (funkcionalno jedinstveni ID zahtjeva koji na serverskoj strani sprječava duplikate) ili ako je POST semantički idempotentan (rijetko, ali moguće).

Ako ne kontroliraš API, ovo je mjesto gdje kao tehnički lead moraš donijeti odluku: ili prihvatiš „nema ponovnog pokušaja za POST“ (i zato implementiraš bolje poruke o pogreškama/mehanizme za resync), ili pregovaraš s ponuđačem API-ja o Idempotency-Keyu ili modelu koji omogućuje deduplikaciju.

429 Too Many Requests: poštujte rate-limite umjesto „ponovnog pucanja“

HTTP 429 nije „smetajuća poruka o pogrešci“, nego mehanizam upravljanja. U poslovnim okruženjima 429 često potječe od:

• API-Gateway s Token-Bucket/Leaky-Bucket ograničenjima (Rate Limiting).
• Cloud-API-ji s ograničenjima po korisniku po minuti/satu.
• Interni servisi koji se štite od vrhova opterećenja.

Za klijenta to znači: Ponovni pokušaji – da, ali kontrolirano. Važne su dvije stvari:

• Pročitati Retry-After-header ako je prisutan (sekunde ili HTTP-datum).
• Koristiti Backoff ako nema Retry-After ili ako dodatno primjenjuješ jitter.

Najčešća zamka: 429 se tretira kao 500 („Serverfehler, retry sofort“). Time pojačavaš ograničavanje kapaciteta (throttling). Bolje je: 429 je signal za aktivno čekanje i po potrebi smanjenje paralelizma.

Backoff s Jitterom: zašto bez slučajnosti sve sinkrono kolabira

Exponential Backoff znači da nakon svakog neuspjelog pokušaja povećavaš vrijeme čekanja (npr. 200 ms, 400 ms, 800 ms …). Jitter je komponenta slučajnosti koja sprječava da se mnogi klijenti istovremeno ponovno jave. Bez Jittera u praksi se često dogodi sljedeće: aktivira se limit, 50 klijenata dobije 429, svi čekaju točno 1 sekundu i onda ponovno šalju istovremeno. Rezultat: opet 429 i dobiješ „Thundering Herd“ problem.

Praktičan pristup je „Full Jitter“ ili „Equal Jitter“: izračunaš Backoff-interval i zatim odabereš nasumično vrijeme čekanja unutar tog intervala. To zvuči kao detalj, ali u radu čini razliku između stabilnog oporavka i stalnog ponavljanja pogrešaka.

Jasan obrazac: kapsulirajte REST-pozive umjesto da svugdje raspoređujete petlje ponovnog pokušaja

Ako ugrađuješ Retries/Backoff „ad hoc“ na svakoj točki poziva, brzo nastaje nekonzistentno ponašanje: jedan endpoint agresivno ponavlja pokušaje, drugi uopće ne, logiranje je nepotpuno, a administratori vide samo „sporadične pogreške“. Robusno postaje tek kada definiraš centralni put poziva:

• Omotač oko RESTClient/RESTRequest koji primjenjuje politiku (Timeout, Retry, Backoff).
• Jedinstveni objekt rezultata: statusni kod, trajanje, brojač pokušaja, eventualno zadnja iznimka.
• Standardizirano logiranje (Request-ID/Correlation-ID, endpoint, HTTP-metoda, relevantna zaglavlja).

To je točka u kojoj se dodatni kod zaista isplati: dobivaš reproducibilno ponašanje, bolje logove i možeš konfigurirati politike po ciljnom sustavu bez mijenjanja aplikacije.

Matrica odluka za politiku (kratko i praktično)

Za većinu integracija dovoljna je jednostavna matrica koju implementiraš u omotaču:

• Ponovni pokušaj za: mrežne pogreške/prekidi veze, 408, 429, 502, 503, 504 (ovisno o API-ugovoru).
• Bez ponovnog pokušaja pri: 400/401/403/404 (uglavnom konfiguracija/autentikacija/pogreška zahtjeva), 409/422 (poslovni konflikti/validacija), kao i kod POST-a bez idempotencijskog ključa.
• Maks. pokušaja: držati malo (često 2–4 pokušaja su dovoljna), uz bolje nadgledanje.
• Maks. Backoff: ograničiti (npr. nekoliko sekundi do jedne minute), inače blokiraš previše worker-a.

Važno: ova pravila nisu univerzalna. 404 može kod „eventualne konzistencije“ biti tranzijentna, 409 može biti tranzijentna kod strategija zaključavanja. Razlika je u tome: tada je to svjesna devijacija, a ne slučajno ponašanje.

Konkretan rubni slučaj: timeout nakon POST-a – je li to sada bilo pohranjeno ili nije?

Ovo je klasik koji se rijetko čisto reproducira u debuggeru: pošalješ POST (npr. „kreiranje ticketa“), tvoj klijent dobije Read-Timeout, a korisnik klikne „ponovo“. U backendu ticket već postoji. Bez protumjere nastaju duplikati ili nekonzistentnosti.

Robustno će to biti samo s jednom od tri strategije:

• Idempotency-Key: Generiraš za svaki poslovni postupak jedinstveni ID zahtjeva (npr. GUID), šalješ ga kao header, a server garantira deduplikiranu obradu.
• Client-seitige Deduplizierung: Spremaš „pending requests“ lokalno sa vlastitim ID-jem i nakon timeouta radiš provjeru statusa (npr. GET po poslovnom ključu). To je zahtjevnije i nije uvijek moguće.
• Kein Retry: Jasno prijaviš da je status nepoznat i uvedeš ručni/automatski proces resinkronizacije (npr. naknadno usklađivanje).

Ako gradiš integracije za operativu, „Status nepoznat“ je valjana kategorija. Ne pokušavaj neizvjesnost isprogramirati. Logiraj je, učini je vidljivom i osiguraj put za usklađivanje.

Backoff-dizajn u praksi: granice, paralelnost i otkazivanje

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

• Parallelität: Ako imaš 20 threadova i svi čekaju, 20 threadova je blokirano. Za servise je to često u redu, za desktop-aplikacije obično nije.
• Cancel: Korisnik prekida, servis se zaustavlja, posao se završava. Čekanje u backoffu mora se moći prekinuti, inače procesi zaustavljanja/gašenja ostaju zaglavljeni.
• Fairness: Više endpointa ne bi smjelo međusobno izgladnjivati. Rate-limiti su često po tokenu ili po endpointu; tvoj wrapper trebao bi moći upravljati po ciljnom sustavu.

Ispravan pristup je: implementirati backoff u funkciji koja čeka u malim intervalima i pri tome provjerava cancel-flag (npr. Event/Token). To nije luksuz: upravo to mjesto odlučuje hoće li Windows- i Linux-servisi pravilno stati ili u Service Control Manager konzoli „zaglavljivati“.

Maksimalno trajanje i „vremenski budžet“ po pozivu

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

Debugging i dijagnostika u radu: Bez dobrih logova retriji su nevidljivi pojačivači grešaka

Ponovni pokušaji bez zapisivanja logova su rizični, jer na kraju čuješ samo „ponekad traje“. Ako želiš sustav učiniti robusnim, trebaš logove koji ne samo ispisuju iznimke, nego i daju kontekst:

• Correlation-ID: ID zahtjeva koji generiraš za svaki poziv i koji zadržavaš kroz sve ponovne pokušaje.
• Broj pokušaja i kašnjenje (Backoff).
• HTTP-status i odabrana zaglavlja (posebice Retry-After, RateLimit-zaglavlja ako postoje).
• Trajanje po pokušaju i ukupno trajanje.
• Endpoint (Host + putanja), ali bez osjetljivih podataka u logu (tokeni, osobni podaci).

Za tehničke leadove je to osim toga poluga za podešavanje granica: vidiš događaju li se time‑outi „uvijek pri 3 sekunde“ (vjerojatno premalo) ili dolazi li 429 u valovima (paralelnost je previsoka, backoff preslab ili nedostaju klijentski rate‑limiti).

Tipične zamke u logiranju

• Previše payloada: kompletno logiranje JSON tijela izgleda korisno, ali eksplodira kod datoteka/priloga i stvara probleme s privatnošću. Bolje: hash/veličina, Content-Type, i po potrebi ciljano debug-logiranje preko feature‑flaga.
• Nema razlike između timeout i cancel: prekinuti poziv nije greška u istom smislu kao timeout. Razdvoji ih, inače administratori love fantomske greške.
• Ponovni pokušaj prekriva prvotni uzrok: ako pokušaj 1 ima TLS-pogrešku, a pokušaj 2 uspije, ipak želiš znati da je postojao kratkotrajni TLS-problem. To je rani signal upozorenja.

Klijentsko ograničavanje brzine (Rate-Limiting): Wenn du die Last selbst steuern musst

429 je odgovor servera. U mnogim scenarijima je ipak smisleno već na strani klijenta ograničiti promet prije nego što počneš proizvoditi 429. To je posebno relevantno ako:

• imaš batch-jobove (npr. noćna usklađivanja podataka) i API dopušta samo X zahtjeva po minuti.
• koristiš više worker‑a/dretvi i zahtjeve šalješ paralelno.
• pokrećeš više instanci procesa (npr. terminalserver ili više servisa).

Praktično to znači: implementiraš mali rate‑limiter (npr. Token‑Bucket) po ciljnom sustavu ili po API‑keyu. To smanjuje 429, stabilizira protok i čini vremena izvršavanja bolje predvidljivima. Za operacije i planiranje kapaciteta to je često 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 privremenu preopterećenost. Tko ima samo backoff, konstantno „ide glavom kroz zid“ i potom usporava. Tko ima samo rate‑limiter, loše reagira na iznenadne limite ili dijeljene kvote (npr. kad više sustava koristi isti API‑Key).

Sigurnost i usklađenost: ponovni pokušaji ne smiju prikrivati probleme s autentifikacijom

U kompanijama su autentikacija i autorizacija često najčešći „problem“ nakon deploymenta: istekli tokeni, pogrešno konfigurirane klijentske vjerodajnice, nedostajuće proxy‑iznimke. Ponovni pokušaji tu ne pomažu i mogu biti štetni jer pune logove i pokreću mehanizme zaključavanja (npr. zaključavanje računa, rate‑limiti na auth endpointima).

Praktično pravilo: 401/403 nikad ne pokušavati ponovno (osim ako imaš namjerno rukovanje osvježavanjem tokena). Ako implementiraš osvježavanje tokena, jasno ga odvoji od retry‑mehanizma: prvo obnovi token, pa potom jednom ponovno pošalji zahtjev. I zabilježi eksplicitno da je osvježavanje izvršeno.

Kad se trud isplati – i kada ne

Robusni ponovljeni pokušaji (retries) i backoff nisu cilj sami po sebi. Isplate se posebno kad vrijedi barem jedna od sljedećih toč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. prozor za zadatke, mjesečno zatvaranje) i želiš proći stabilno.
• Pokrećeš ga kao servis/daemon i mora biti predvidivo i uredno zaustavljiv.

Manje se isplati ako imaš isključivo „potvrđujuće GET-ove“ u UI-u i korisnik ionako ponovno klikne, ili ako radiš u internom, vrlo stabilnom okruženju bez kvota i greške su odmah vidljive. Čak i tada su uredni timeouti i logiranje gotovo uvijek smisleni.

Pragmatični kontrolni popis za produkcijski rad Delphi-REST klijenta

• Timeouts: konfigurabilni po endpointu, realno postavljeni, definirano ukupno vremensko ograničenje.
• Retry-Policy: ovisno o HTTP-metodi i idempotenciji, ne općenito.
• 429-Handling: obraditi Retry-After, backoff s jitterom, paziti na paralelnost.
• Abbruchpfad: čekanje backoffa moguće prekinuti (zaustavljanje servisa, otkaz korisnika).
• Logging: Correlation-ID, Attempt, Delay, trajanje, Status/Headers – bez tajni.
• Optional: rate-limiter na strani klijenta za batch/parallelni rad.

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

S RESTClient in Delphi brzo ostvariš funkcionalne REST pozive. U produkcijskoj upotrebi postaje robusno tek kad svjesno definiraš timeout-e, stručno osiguraš retries (Idempotenz!), i poštuješ 429 rate-limite s backoffom i jitterom. Kod za to nije kompliciran, ali mora biti centraliziran, konfigurabilan i jasno promatran. Tek tada se trud isplati: manje „sporadičnih“ tiketa, bolja dijagnostika u radu i integracije koje ni pod opterećenjem ne zapinju.

Ako želiš takvu retry-/backoff-politiku uredno uvesti u postojeće Delphi aplikacije ili je pravilno dimenzionirati za novu integraciju: Kontakt aufnehmen.

Za ovu temu su također važni Delphi Restclient Timeout i Retry-Strategie Delphi. Članak ove aspekte jasno razvrstava i pokazuje na što treba paziti u praksi.

Raspraviti projekt ili modernizacijski zahvat s Net-Base.