Geliştirme

API Retry Rehberi: Backoff ve Jitter Ne Zaman Kullanılır?

Mehmet Fatih Ünal
31 Ekim 2026
6 dk okuma
#API#Retry#Backoff#Jitter#Idempotency#Backend
API Retry Rehberi: Backoff ve Jitter Ne Zaman Kullanılır?

API retry, backoff ve jitter nedir?

API retry başarısız bir işlemi yeniden denemektir. Backoff denemeler arasına bekleme koyar; jitter ise istemcilerin aynı anda tekrar yüklenmesini azaltmak için bu beklemeye rastgelelik katar. Birlikte kullanıldıklarında geçici bir sorunun ek trafikle büyümesini sınırlamaya yardımcı olabilirler.

Amazon'un yeniden deneme rehberi, timeout, retry ve beklemeyi aynı tasarımın parçaları olarak ele alır. Bir servisin yavaşlaması sırasında bütün istemcilerin hemen yeniden denemesi, toparlanmaya çalışan servise daha fazla iş yükler.

Örneğin ürün bilgisi alan bir yönetim ekranını düşünün. Ağ kısa süreli kesildiğinde tek bir yeniden deneme kullanışlı olabilir. Eksik bir zorunlu alan yüzünden reddedilen aynı gövdeyi art arda göndermek ise sorunu düzeltmez. İlk karar, hatanın hangi sınıfta olduğudur.

Hangi hatalar yeniden denenmeli?

Yeniden deneme kararı, hatanın geçici olmasına ve işlemin güvenle tekrarlanabilmesine dayanmalıdır. Bir HTTP durum kodu tek başına bütün sözleşmeyi anlatmaz; sağlayıcının hata belgeleri ve işlem türü de okunmalıdır.

Bir doğrulama hatasında kullanıcı girdisinin değişmesi gerekebilir. Yetki hatasında hesap veya erişim bilgisi incelenmelidir. Geçici servis erişilemezliği ise sınırlı bir yeniden denemeye uygun olabilir. AWS backoff deseni, kalıcı hatalarla geçici hataları ayırmayı ve aşırı tekrarın yük etkisini tartışır.

İstemci kütüphanenizin zaten retry yapıp yapmadığını da kontrol edin. Uygulama üç deneme, alt katmandaki istemci üç deneme yaparsa tek kullanıcı işlemi dokuz ağ çağrısına çıkabilir. Bu sayı yalnızca katmanların çarpılmasını gösteren örnektir; bir sağlayıcının varsayılanı değildir.

Timeout, işlemin gerçekleşmediğini kanıtlar mı?

Timeout, istemcinin bekleme sınırına ulaştığını gösterir; uzak tarafta hiçbir etki oluşmadığını kanıtlamaz. Sunucu kaydı oluşturmuş fakat cevap istemciye ulaşmamış olabilir.

Bir sipariş oluşturma isteğini aynı gövdeyle tekrar göndermek bu nedenle dikkat ister. API idempotency destekliyorsa aynı mantıksal işlem boyunca aynı anahtarı koruyun. Her denemede yeni anahtar üretmek, tekrarı yeni bir işlem gibi gösterebilir.

Sağlayıcının saklama süresini, anahtar kapsamını ve farklı gövdeyle tekrarın davranışını okuyun. Gelen olaylar açısından aynı sınırı webhook idempotency rehberi inceler. İstek ve olay teslimatı aynı mekanizma olmasa da tekrarın yan etkisini ayrıca düşünmek ikisinde de gereklidir.

Exponential backoff ve full jitter nasıl hesaplanır?

Exponential backoff, bekleme üst sınırını her denemede büyütür; full jitter bu sınırın içinden rastgele bir süre seçer. Üst sınır koymak, beklemelerin kontrolsüz uzamasını önler. AWS'nin jitter incelemesi farklı dağıtım yaklaşımlarını karşılaştırır.

Aşağıdaki JavaScript işlevi yalnızca bekleme süresini hesaplar. HTTP isteği göndermez ve hata sınıflandırması yapmaz:

export function retryDelayMs(attempt, random = Math.random) {
  if (!Number.isInteger(attempt) || attempt < 0) {
    throw new RangeError('attempt must be a non-negative integer');
  }

  const ceiling = Math.min(5000, 250 * 2 ** attempt);
  return Math.floor(random() * ceiling);
}

attempt sıfırdan başlar ve ilk yeniden denemeyi temsil eder. 250 ve 5000 değerleri örnek politika parametreleridir; servisinize uygun oldukları ölçülmeden varsayılmamalıdır. Testte random yerine sabit bir işlev geçirerek sınırları deterministik biçimde kontrol edebilirsiniz.

Rastgele beklemek başarı garantisi vermez. İşlemin neden yeniden denendiği, kaç kez deneneceği ve ne zaman vazgeçileceği hâlâ ayrı kararlardır.

Retry-After başlığı geldiğinde ne yapılmalı?

Retry-After, yeniden denemeden önce beklenmesi istenen süreyi bir saniye değeri veya HTTP tarihiyle bildirebilir. RFC 9110, bu başlığın biçimini tanımlar. RFC 6585 ise 429 Too Many Requests yanıtının bu başlığı içerebileceğini belirtir.

Örnek bir sunucu yanıtı:

HTTP/1.1 429 Too Many Requests
Retry-After: 30

Bu durumda kendi kısa jitter sürenizi seçip otuz saniyeden önce yeniden göndermek, sunucunun talebini izlemek olmaz. Sunucu beklemesini alt sınır olarak ele alın; toplam kullanıcı bekleme bütçesine sığmıyorsa işlemi ertelemek veya açık bir hata göstermek gerekebilir.

Tarih biçimindeki değeri yorumlarken saat farkını, geçersiz başlıklarda uygulanacak politikayı ve üst bekleme sınırını da düşünün. Buradaki retryDelayMs işlevi Retry-After ayrıştırıcısı değildir.

Deneme sayısı ve toplam süre nasıl sınırlandırılır?

Güvenilir bir retry politikası hem deneme sayısını hem toplam zamanı sınırlar. "Üç deneme" ifadesinin ilk isteği içerip içermediğini açıkça yazın; kullanıcı beklerken bu fark önemlidir.

Her çağrının timeout süresi ile aradaki beklemeler toplam bütçenin içindedir. Kullanıcı işlemi iptal ettiğinde sonraki denemelerin de durması gerekir. Bekleyen bir ekranın arka planda sınırsız istek üretmesine izin vermeyin.

Gözlem için mantıksal işlem kimliğini, deneme numarasını, hata sınıfını ve seçilen beklemeyi kaydedin; hassas istek gövdelerini loglamak zorunda değilsiniz. Başarılı işlem sayısıyla toplam ağ denemesi sayısını ayrı okumak, görünmeyen tekrar yükünü fark etmeyi kolaylaştırır.

Retry politikasını hangi senaryolarla denemeli?

Bir retry denemesi, başarı kadar vazgeçme davranışını da doğrulamalıdır. Geçici hatadan sonra başarı, kalıcı hatada hemen durma, üst deneme sınırı, kullanıcı iptali ve Retry-After senaryolarını ayrı çalıştırın.

Bekleme işlevini testte gerçek zaman geçirmek yerine denetlenebilir bir zamanlayıcıyla değiştirin. Aynı işlem için iki kayıt oluşmadığını da gözleyin. Veritabanındaki benzersizlik kurallarını planlarken PostgreSQL indeks rehberi, okuma performansı kararları için ek bağlam sunar; bir performans indeksi tek başına idempotency tasarımı değildir.

Sık sorulan sorular

Her 500 yanıtı yeniden denenmeli mi? Hayır. Hatanın nedeni, sağlayıcı sözleşmesi ve işlemin tekrar güvenliği değerlendirilmelidir.

Jitter ile backoff aynı şey mi? Hayır. Backoff bekleme politikasını, jitter ise denemeleri zamana yaymak için kullanılan rastgeleliği ifade eder.

Timeout alan POST isteği kesin başarısız mı? Hayır. Sunucuda yan etki oluşmuş olabilir; tekrar öncesinde idempotency veya durum sorgulama sözleşmesi gerekir.

Retry-After toplam bütçeden uzunsa ne yapmalı? Sunucuyu erken zorlamak yerine işlemi erteleyin veya bütçeye uygun bir sonuç döndürün.

Daha Fazla İçerik

Blog sayfasında diğer yazılarımı keşfedin

Tüm Yazılar