REST İstemcisi Delphi içinde: Zaman aşımı, yeniden denemeler ve 429 rate limit'lerine karşı backoff ile dayanıklı

Bir REST çağrısı teoride basittir: İstek gönder, yanıt al, tamam. Pratikte üretim entegrasyonları nadiren “yanlış URL” nedeniyle başarısız olur; sorunlar işletmede ortaya çıkan kenar durumlarındadır: aralıklı timeoutlar, kısa süreli DNS veya TLS problemleri, aşırı yüklü downstream sistemleri veya bir API gateway’in kısıtlaması nedeniyle oluşan 429 (Too Many Requests). Tam da burada bir demo-prototip ile sürekli işletilebilir bir entegrasyon ayrışır.

Bu yazı, RESTClient ile Delphi içinde nasıl sağlam iletişim yolları kuracağınızı gösterir: net timeout tanımları, yalnızca işlemsel ve teknik açıdan güvenli olduğunda hedeflenmiş yeniden denemeler (retries) ve rate limitleri daha da kötüleştirmeyen bir geri çekilme (backoff) davranışı. Odak “güzel kod” değil; yük altındaki davranış, hata ayıklama kabiliyeti, temiz hata sınıflandırması ve ek çabanın ne zaman gerçekten değerli olduğu üzerinedir.

Gerçek ortamda neden timeoutlar, yeniden denemeler ve 429 birlikte ortaya çıkar

Kurumsal ağlarda REST çağrıları nadiren “doğrudan internete” çıkar. Tipik olarak proxy zincirleri, TLS terminasyonu, API gateway’ler, WAF’ler (Web Application Firewall) ve birden çok iç hop bulunur. Her bileşen kendi timeout’ları ve limitlerine sahip olabilir. Client tarafında görülen bir timeout şunlardan biri anlamına gelebilir:

• Sunucu yanıt vermedi (aşırı yük, deadlock, downstream kilitlenmiş).
• Yanıt geldi ama çok geç (kötü yol, paket kaybı, tıkanıklık).
• Kendinizi dışarıda bıraktınız: çok kısa timeout’lar veya engelleyen UI/ana iş parçacığı.

Eş zamanlı olarak “naif” yeniden denemeler (retries) genellikle daha fazla probleme yol açar: Sunucu zaten sınırındaysa yeniden denemeler yükü artırır ve küçük bir darboğazı büyük bir arızaya dönüştürür. 429 durumunda bu daha açıktır: Bir rate-limit, daha az göndermeniz veya daha sonra tekrar denemeniz için açık bir istektir. Backoff uygulamayan bir client kazara DoS davranışı sergileyebilir.

Bu nedenle sağlamlık “her yerde yeniden dene” ile değil, bir tutarlı karar modeli ile sağlanır: Hangi hatalar geçici (transient), hangileri kalıcı; hangi istekler yeniden denenebilir (idempotent); ve bekleme sürelerini sisteminizin stabil kalmasını sağlayacak şekilde nasıl yönlendirirsiniz?

Timeoutları doğru ayarlamak: Delphi içindeki RESTClient için “Timeout” tam olarak ne demek?

Sıklıkla takılan bir nokta: “Timeout” hepsi aynı şey değildir. Stack’e göre farklı safhalar vardır. Delphi-REST-komponentleri birçok detayı kapsüllese bile, modeli kafanızda tutmalısınız:

• Connect-Timeout: TCP bağlantısının kurulmasına kadar geçen süre (uygulamaya göre DNS/TLS dahil olabilir).
• Read/Response-Timeout: Sunucudan byte gelmeye veya yanıtın tamamlanmasına kadar geçen süre.
• Toplam-Timeout: Yeniden denemeler de dahil olmak üzere tüm çağrı için üst sınır.

Pratikte çok kısa bir timeout en azından çok uzun olan kadar tehlikelidir: Yapay hatalar üreterek bunların yeniden denenmesine ve dolayısıyla yük artışına neden olursunuz. Tersine çok uzun bir timeout worker thread’leri, kuyruk slotlarını veya UI tepki verebilirliğini bloke eder. İşletme ve yönetim açısından önemli olan, timeout’ların yapılandırılabilir olmasıdır (örneğin endpoint başına) ve log’a kaydedilmeleridir.

Pratik öneri: Tek bir sayı yerine iki seviye

İş yazılımlarında REST çağrıları için iki seviye işe yarar:

• Call-Timeout (istek başına): kullanım senaryosuna uygun gerçekçi bir üst sınır.
• İş zaman aşımı (üst düzey): bir toplu işlem veya senkronizasyon işi varsa, toplam çalıştırma süresini sınırlayın ve düzgün bir şekilde sonlandırın.

Bu, tek bir API yanıtının sonsuza dek beklemesini engeller ve aynı zamanda gece çalıştırılan bir işin çok sayıda yeniden deneme nedeniyle “öğlene kadar” çalışmasını önler.

Yeniden denemeyi doğru kararlaştırma: teknik değil, iş mantığına göre

Bir yeniden denemenin izinli olup olmadığı tamamen teknik bir konu değildir. Temel kavram İdempotenz (idempotans): Bir istek, birden çok kez çalıştırıldığında tek seferlik çalıştırmayla aynı etkiyi oluşturuyorsa idempotent kabul edilir. Tipik örnekler: GET idempotentdir, PUT çoğunlukla (hedef nesneyi tamamen set ediyorsanız) öyle olur, DELETE genelde öyledir. POST ise çoğunlukla idempotent değildir (ör. “yeni bir sipariş oluştur” gibi).

Bu neden belirleyici? Bir zaman aşımı, sunucunun isteği işlemiş olabileceği ama yanıtın istemciye ulaşmadığı anlamına gelebilir. Eğer körü körüne bir POST’u tekrar ederseniz, çoğaltmalar üretebilirsiniz. Bu işletmede klasik bir „hayalet hata“dır: Uygulamada „Timeout“ görünüyor, ancak backend’de çift kayıtlar oluşmuştur.

Güvenli temel: sadece açıkça yeniden denenebilir işlemler için yeniden deneme

Entegrasyonlarda işe yaradığı kanıtlanmış sağlam bir kural:

• GET: geçici hatalarda yeniden denenebilir.
• PUT/DELETE: API’niz bunu iş mantığı açısından net tanımlıyorsa (ör. kaynak-ID sabitse) ve sunucu idempotent olarak doğru uygulanmışsa yeniden denenebilir.
• POST: yalnızca bir Idempotency-Key stratejiniz varsa (sunucu tarafında çoğaltmayı önleyen işlem açısından benzersiz istek-ID’si) veya POST semantik olarak idempotent ise (nadir ama mümkün).

API’yi kontrol etmiyorsanız, burada teknik lider olarak bir karar vermeniz gerekir: Ya „POST için yeniden deneme yok“ kabul edersiniz (ve bunun için daha iyi hata mesajları / yeniden eşitleme mekanizmaları yaparsınız), ya da API sağlayıcısıyla bir Idempotency-Key veya deduplike edilebilen bir model konusunda müzakere edersiniz.

429 Too Many Requests: Rate-Limitlere saygı gösterin, „kaybolana kadar yeniden denemeyin“

HTTP 429 bir „rahatsız edici hata“ değil, bir kontrol mekanizmasıdır. Kurumsal ortamlarda 429 genellikle şunlardan kaynaklanır:

• Token-Bucket/Leaky-Bucket limitleri olan bir API-Gateway (Rate Limiting).
• Dakika/saat başına kiracı başına limitleri olan bulut API’leri.
• Yük dalgalarına karşı kendini koruyan dahili servisler.

İstemci için bunun anlamı: Evet yeniden dene, ama kontrol altında. İki önemli nokta vardır:

• Retry-After başlığını varsa değerlendirin (saniye veya HTTP tarihi).
• Backoff kullanın, Retry-After yoksa veya ayrıca jitter uyguluyorsanız.

En sık yapılan hata: 429’u 500 gibi işlemek („Sunucu hatası, hemen yeniden dene“). Bu, daraltmayı güçlendirir. Daha doğru olan: 429 bir sinyaldir — aktif olarak beklemeyi ve gerekirse paralellik düzeyini azaltmayı gerektirir.

Jitter ile Backoff: rastgelelik olmadan her şey neden eşzamanlı çöker

Exponential Backoff, her başarısız denemeden sonra bekleme süresini artırman anlamına gelir (ör. 200 ms, 400 ms, 800 ms …). Jitter, birçok istemcinin aynı anda tekrar bağlanmasını engelleyen rastgele bir bileşendir. Jitter olmadan pratikte sıkça şu durum gerçekleşir: Bir limit devreye girer, 50 istemci 429 alır, hepsi tam olarak 1 saniye bekler ve sonra tekrar aynı anda gönderir. Sonuç: yeniden 429 ve bir „Thundering Herd“-Problem ortaya çıkar.

Pratikte işe yarayan bir yaklaşım „Full Jitter“ veya „Equal Jitter“dir: Bir backoff penceresi hesaplayıp bu pencere içinde rastgele bir bekleme süresi seçersiniz. Bu ayrıntı gibi görünse de işletimde istikrarlı bir toparlanma ile sürekli başarısız döngü arasındaki farkı yaratır.

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

Eğer Retries/Backoff’u her çağrı noktasına „ad hoc“ eklerseniz, hızla tutarsız davranışlar ortaya çıkar: bir endpoint agresifçe retry yapar, diğeri hiç yapmaz, Logging eksik kalır ve yöneticiler sadece „sporadische Fehler“ görür. Daha sağlam olur eğer merkezi bir çağrı yolu tanımlarsınız:

• RESTClient/RESTRequest etrafında bir wrapper, Politika (Timeout, Retry, Backoff) uygulayan.
• Tek tip sonuç nesnesi: durum kodu, süre, deneme sayacı, gerekirse son Exception.
• Standartlaştırılmış Logging (Request-ID/Correlation-ID, Endpoint, HTTP yöntemi, ilgili Header).

İşte ekstra kodun gerçekten değdiği nokta: Tekrarlanabilir davranış, daha iyi loglar elde edersiniz ve uygulamayı yeniden inşa etmeden hedef sistem başına politikaları yapılandırabilirsiniz.

Politika karar matrisi (kısa ve pratik)

Çoğu entegrasyon için wrapper içinde uygulayacağınız basit bir matris yeterlidir:

• Retry yapılacak durumlar: Ağ hataları/bağlantı kopmaları, 408, 429, 502, 503, 504 (API sözleşmesine göre).
• Retry yapılmamalı: 400/401/403/404 (çoğunlukla konfigürasyon/kimlik doğrulama/istek hatası), 409/422 (iş mantığı çatışmaları/doğrulama), ve Idempotency-Key olmadan yapılan POST işlemleri.
• Maks. deneme sayısı: düşük tutun (genellikle 2–4 deneme yeterlidir), bunun yerine daha iyi izleme.
• Maks. Backoff: sınırlandırın (ör. birkaç saniye ile bir dakika arası), aksi halde çok fazla Worker’ı engellersiniz.

Önemli: Bu kurallar evrensel değildir. 404 „eventual consistency“ durumunda geçici (transient) olabilir, 409 kilitleme stratejilerinde geçici olabilir. Fark şudur: Bu durumda bilinçli bir sapma olur, rastgele davranış değil.

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

Bu, hata ayıklayıcıda nadiren temiz şekilde yeniden üretilebilen klasik bir durumdur: Bir POST gönderirsiniz (ör. „Ticket oluştur“), istemciniz bir okuma zaman aşımı alır ve kullanıcı „tekrar“ tıklar. Ancak arka uçta bilet zaten vardır. Karşı önlem alınmazsa çoğaltmalar veya tutarsızlıklar ortaya çıkar.

Sağlam çözüm ancak şu üç stratejiden biriyle elde edilir:

• Idempotency-Key: Her bir iş süreci için benzersiz bir Request-ID (ör. GUID) oluşturursunuz, bunu header olarak gönderirsiniz ve sunucu işleme sırasında deduplikasyonu garanti eder.
• Client-seitige Deduplizierung: Bekleyen istekleri kendi kimliğiyle yerel olarak saklarsınız ve zaman aşımından sonra bir durum kontrolü yaparsınız (ör. iş anahtarına göre GET). Bu daha zahmetlidir ve her zaman mümkün değildir.
• Kein Retry: Durumun bilinmediğini düzgün şekilde bildirirsiniz ve elle/otomatik bir yeniden eşitleme süreci kurarsınız (ör. daha sonra karşılaştırma).

Operasyon için entegrasyonlar oluşturuyorsanız, „Durum bilinmiyor“ geçerli bir kategoridir. Belirsizliği kodla yok etmeye çalışmayın. Bunları loglayın, görünür kılın ve bir eşleme yolu sağlayın.

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

Bir Backoff sadece „uyku“ değildir. Bunu uygulamanızın bağlamına yerleştirmeniz gerekir:

• Parallelität: 20 iş parçacığınız (thread) varsa ve hepsi bekliyorsa, 20 iş parçacığı bloke olur. Servisler için bu genellikle kabul edilebilir, masaüstü uygulamaları için değil.
• Cancel: Bir kullanıcı işlemi iptal eder, servis durur, bir iş sonlandırılır. Backoff beklemeleri iptal edilebilir olmalı, aksi takdirde durdurma/kapama süreçleri takılabilir.
• Fairness: Birden fazla uç nokta birbirini aç bırakmamalı. Rate-Limits genellikle token başına veya uç nokta başına uygulanır; wrapper’ınız hedef sistem bazında kontrol sağlayabilmelidir.

Temiz bir yaklaşım şudur: Backoff’u küçük aralıklarla bekleyen ve bu sırada bir iptal bayrağını (ör. Event/Token) kontrol eden bir fonksiyona koymak. Bu lüks değil: Tam da bu nokta, bir Windows- und Linux-Servicesin düzgün şekilde durup durmayacağını veya Service Control Manager konsolunda „takılıp“ kalacağını belirler.

Maximaldauer und „Budget“ pro Call

Sağlam bir Retry-uygulaması yalnızca „maks deneme“ ile çalışmaz, aynı zamanda bir süre bütçesi ile de çalışır. Örnek: Çağrı için yeniden denemeler dahil olmak üzere maksimum 10 saniye toplam süre izin verirsiniz. Böylece tek bir deneme, yanlış ayarlanmış bir timeout yüzünden aniden 30 saniye bloke edemez. Yöneticiler ve işletme için bu çok değerlidir; gecikme zirvelerini sınırlar ve kuyrukları stabilize eder.

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

Günlüğe kaydetme olmadan yeniden denemeler tehlikelidir; çünkü sonunda sadece „bazen sürüyor“ duyarsınız. Daha sağlam olmak istiyorsanız, yalnızca Exception vermeyen, aynı zamanda bağlam sağlayan loglara ihtiyacınız var:

• Correlation-ID: her çağrı için oluşturduğunuz ve her yeniden denemede koruduğunuz bir istek kimliği.
• Deneme numarası ve Gecikme (Backoff).
• HTTP durumu ve seçilmiş headerlar (özellikle Retry-After, varsa RateLimit headerları).
• Her deneme için süre ve toplam süre.
• Uç nokta (Host + Pfad), ancak loglarda hassas veri olmamalı (tokenlar, kişisel veriler).

Teknik liderler için bu aynı zamanda sınırları ayarlamak için bir kaldıraçtır: Timeout’ların „hep 3 saniyede“ mi oluştuğunu görürsünüz (muhtemelen çok kısa) ya da 429’un dalgalar halinde gelip gelmediğini (paralellik çok yüksek, backoff çok zayıf veya istemci tarafı oran sınırlamaları eksik).

Tipik log tuzakları

• Çok fazla payload: JSON gövdelerini tamamen loglamak faydalı görünür, ancak dosyalar/ekler söz konusu olduğunda patlar ve veri koruma sorunları yaratır. Daha iyi: Hash/boyut, Content-Type ve gerektiğinde özellik bayrağıyla hedeflenmiş hata ayıklama loglaması.
• Timeout ile iptal ayrımının olmaması: İptal edilmiş bir çağrı, bir timeout ile aynı türde bir hata değildir. Bunları ayırın, aksi halde yöneticiler hayalet hataları takip eder.
• Retry ilk nedeni örtbas eder: Eğer deneme 1 bir TLS hatası veriyorsa ve deneme 2 başarılı oluyorsa, yine de bir TLS dalgalanması olduğunu bilmek istersiniz. Bu erken uyarı işaretidir.

İstemci tarafı oran sınırlaması: Yükü kendiniz yönetmeniz gerektiğinde

429 sunucunun yanıtıdır. Birçok senaryoda ise 429 üretmeden önce istemci tarafında düşürmek mantıklıdır. Bu özellikle geçerlidir eğer:

• Toplu işleriniz (ör. gece veri eşleştirme) var ve API dakika başına yalnızca X istek izin veriyorsa.
• Birden fazla worker/iş parçacığı kullanıyor ve istekleri paralel olarak fırlatıyorsanız.
• Birden fazla süreç örneği çalışıyorsa (ör. terminal sunucu veya birden fazla servis).

Pratikte bunun anlamı şudur: Hedef sistem veya API anahtarı başına küçük bir rate-limiter (ör. Token-Bucket) uyguluyorsunuz. Bu 429’u azaltır, verimi stabil hale getirir ve işlem sürelerini daha öngörülebilir kılar. İşletme ve kapasite planlaması açısından bu genellikle „bir retry daha“den daha değerlidir.

Önemli: Rate-Limiter ve Backoff birbirini tamamlar

Rate-limiter sizi normal işletimde limitin altında tutar. Backoff ise yine de 429 veya geçici aşırı yük aldığınızda verilen cevaptır. Sadece backoff olanlar sürekli olarak „duvara çarpar“ ve sonra yavaşlar. Sadece rate-limiter olanlar ise beklenmedik limitlere veya aynı API anahtarını paylaşan birden fazla sisteme karşı kötü tepki verir.

Güvenlik ve Uyumluluk: Yeniden denemeler kimlik doğrulama sorunlarını gizlememeli

Kurumsal ortamlarda dağıtımdan sonra en sık rastlanan „hata“ genellikle kimlik doğrulama ve yetkilendirmedir: süresi dolmuş tokenlar, yanlış yapılandırılmış istemci kimlik bilgileri, eksik proxy istisnaları. Yeniden denemeler burada fayda sağlamaz ve hatta log dosyalarını doldurup kilitleme mekanizmalarını tetikleyerek zarar verebilir (ör. hesap kilitleri, kimlik doğrulama uç noktalarındaki rate-limitler).

Pratik kural: 401/403 asla yeniden denenmemeli (kasıtlı bir token yenileme işleyişiniz yoksa). Eğer token yenileme (Token-Refresh) uyguluyorsanız, bunu retry mekanizmasından net şekilde ayırın: Önce tokeni yenileyin, sonra bir kere yeniden gönderin. Ve açıkça loglayın ki bir yenileme gerçekleşti.

Ne zaman emek harcamaya değer — ve ne zaman değil

Sağlam yeniden denemeler ve backoff kendi başına amaç değildir. Aşağıdaki durumlardan en az biri geçerliyse özellikle fayda sağlarlar:

• Entegrasyon iş açısından kritikse (örn. sipariş alımı, sevkiyat, faturalama).
• API harici veya dahili olarak yalnızca “best effort” şeklinde işletiliyor ve tam kontrole sahip değilsiniz.
• İş yükü zirveleriniz varsa (örn. iş pencereleri, ay sonu işlemleri) ve stabil geçiş istiyorsunuz.
• Bir servis/daemon olarak işletiyorsunuz ve durdurulabilirliğinizi planlı ve temiz tutmanız gerekiyor.

Daha az fayda sağlar eğer arayüzde yalnızca “onay-GET”leri varsa ve kullanıcı zaten yeniden tıklıyorsa, veya kotaların olmadığı çok istikrarlı bir dahili ortamda çalışıyor ve hatalar hemen görünüyorsa. Yine de düzgün zaman aşımı süreleri ve loglama neredeyse her zaman mantıklıdır.

Pragmatische Checkliste für den produktiven Delphi-RESTClient-Betrieb

• Zaman aşımı süreleri: her Endpoint için yapılandırılabilir, gerçekçi seçilmiş, genel zaman bütçesi tanımlanmış.
• Yeniden-deneme-Politikası: HTTP yöntemi ve idempotans’a bağlı olarak, tek tip değil.
• 429-Handling: Retry-After’ı değerlendirin, jitter ile backoff uygulayın, eşzamanlılığı gözetin.
• İptal akışı: backoff beklemesi iptal edilebilir olmalı (servis durdurma, kullanıcı iptali).
• Loglama: Correlation-ID, deneme sayısı, gecikme, toplam süre, durum/başlıklar – gizli bilgiler olmadan.
• Opsiyonel: Batch/Paralel işletim için istemci tarafı rate-limiter.

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

Mit dem RESTClient in Delphi hızlıca çalışan REST çağrılarını elde etmenizi sağlar. Ancak üretimde gerçekten robust olması, zaman aşımı sürelerini bilinçli tanımlamanıza, yeniden denemeleri mesleki olarak güvence altına almanıza (idempotans!), ve 429 rate-limitlerine backoff ve jitter ile saygı göstermenize bağlıdır. Bu kod karmaşık değildir, fakat merkezi, yapılandırılabilir ve düzgün şekilde gözlemlenebilir olmalıdır. Tam da o zaman çaba kendini gösterir: daha az „ara sıra“ oluşan destek kayıtları, işletmede daha iyi teşhis ve yük altında bile aksama yapmayan entegrasyonlar.

Eğer mevcut Delphi uygulamalarına böyle bir Retry-/Backoff-politikasını temizce entegre etmek veya yeni bir entegrasyon için uygun şekilde boyutlandırmak istiyorsanız: iletişime geçin.

Bu konu için Delphi Restclient timeout ve retry-stratejisi de önemlidir. Bu yazı bu yönleri anlaşılır şekilde sıralar ve günlük kullanımda nelere dikkat edilmesi gerektiğini gösterir.

Proje veya modernizasyon çalışmasını mit Net-Base görüşün.