Entegrasyonda 429 Hatası: İstek Sınırı ve Yeniden Deneme

Entegrasyonun döndürdüğü 429 kodu, isteğin yanlış olduğunu değil, çok sık geldiğini söyler: karşı taraf çalışıyordur, belirli bir süre içinde izin verilen istek sayısı aşıldığı için isteğiniz reddedilmiştir. Doğru tepki isteği hemen tekrarlamak değil, artan bekleme süresiyle sıraya almaktır. Hemen tekrarlanan istek sınırı daha da doldurur ve entegrasyon kendi kendini kilitler.

429, 503 ve 403 aynı şey değildir

Kodun hangisi olduğu, yazılımın ne yapacağını belirler. Üçünü aynı torbaya atan bir hata yakalayıcı, çözülebilir bir durumu kalıcı arıza gibi raporlar.

Kuralı basittir: 429 ve 503 bekleyerek geçebilir, 400 ve 403 bekleyerek geçmez. İkinci gruptaki istekleri döngüde tekrar denemek, hem karşı tarafın sınırını boşa harcar hem de gerçek hatayı günlerce görünmez kılar.

İstek sınırı nasıl işler: üç ayrı ölçü

Sınır tek bir sayı değildir. Çoğu arayüzde birbirinden bağımsız üç ölçü aynı anda uygulanır:

• Pencere başına istek: belirli bir zaman diliminde kabul edilen istek sayısı. Pencere dolduğunda yeni istek 429 alır.
• Eşzamanlı bağlantı: aynı anda açık tutulabilen istek sayısı. Toplu aktarımı paralel çalıştıran kod genelde buraya takılır.
• Günlük ya da dönemsel kota: toplam hacim sınırı. Bu dolduğunda beklemek yetmez, gönderim hacmini azaltmak gerekir.

Hangi ölçünün kaç olduğunu tahmin etmeyin: karşı tarafın kendi teknik belgesinde yazılı değer esastır ve sürüm değişince değişebilir. Yanıt başlıklarında kalan istek sayısını ve sınırın ne zaman sıfırlanacağını bildiren alanlar varsa bunlar okunup kayda yazılmalıdır; böylece sınıra ne kadar yaklaşıldığı tahminle değil ölçümle bilinir.

Sınırın kime ait olduğu da sorulmalıdır. Kimi arayüzde sınır anahtar başına, kimisinde hesap, kimisinde çıkış adresi başına uygulanır. Aynı anahtarı hem gece çalışan toplu aktarım hem de gün içindeki kullanıcı ekranları kullanıyorsa, toplu işin doldurduğu sınır yüzünden ekranlar da yanıt alamaz. Riski azaltmanın yolu, farklı işler için ayrı anahtar kullanmak ve toplu işleri yoğun saatlerin dışına almaktır. Anahtarların nerede tutulacağı sır yönetimi yazısında anlatıldı.

Yeniden deneme: artan bekleme ve dağıtılmış zamanlama

Yeniden deneme düzeninin üç kuralı vardır. Birincisi bekleme süresinin her denemede büyümesidir; sabit aralıkla denemek sınırı yeniden doldurur. İkincisi bekleme süresine küçük bir rastgele pay eklemektir: aynı anda 429 alan yüz kayıt, aynı süre sonra yine aynı anda denerse sınır tekrar dolar. Üçüncüsü üst sınırdır; belirli bir deneme sayısından sonra kayıt hata kuyruğuna alınır ve insana görünür hâle gelir.

Yanıt, ne kadar sonra tekrar denenebileceğini söyleyen bir bekleme başlığı döndürüyorsa kendi hesabınızı değil o süreyi kullanın. Sonsuz döngüye izin veren bir yeniden deneme, bir süre sonra karşı tarafın anahtarınızı geçici olarak kapatmasıyla sonuçlanabilir.

Deneme sırasında her başarısız isteğin kaydı tutulmalıdır: hangi kayıt, kaçıncı deneme, dönen kod ve beklenen süre. Bu kayıt olmadan sorunun geçici mi kalıcı mı olduğu tartışmaya kalır; kayıt varsa aynı entegrasyonun hangi saatlerde sınıra takıldığı birkaç günde görünür hâle gelir.

Her istek yeniden denenemez

Bekleme kuralından önce sorulacak soru şudur: bu isteği iki kez göndermek güvenli mi? Sorgulama istekleri güvenlidir. Kayıt oluşturan istekler değildir: 429 aldığınızı düşündüğünüz bir sipariş isteği karşı tarafa ulaşmış ama yanıtı size dönmemiş olabilir. Bu durumda ikinci deneme ikinci kaydı oluşturur.

Çözüm, kayıt oluşturan her isteğe tekrarı tanınabilir kılan bir anahtar koymaktır; karşı taraf aynı anahtarı ikinci kez görürse yeni kayıt açmaz. Bu düzenin ayrıntısı mükerrer kayıt ve idempotency anahtarı yazısında duruyor.

Sınıra takılmayı azaltan altı yol

• Toplu uç kullanın: yüz kaydı tek tek göndermek yerine karşı taraf toplu gönderime izin veriyorsa onu kullanın.
• Değişeni gönderin: tüm katalogu her gece göndermek yerine yalnızca değişen kayıtları aktarın.
• Kuyruk ve hız ayarı koyun: gönderimi doğrudan yapmak yerine kuyruğa yazın; kuyruk tüketicisi saniye başına istek sayısını sınırlı tutar.
• Sorgulamayı bildirime çevirin: durum değişikliğini sürekli sormak yerine webhook ile karşı tarafın haber vermesini sağlayın.
• Önbellek kullanın: saatlerce değişmeyen veriyi her ekran açılışında yeniden istemeyin.
• Zamanı dağıtın: tüm işleri gecenin aynı dakikasına koymayın; aynı anahtarla çalışan işler birbirinin sınırını tüketir.

Kısa kontrol listesi

• Hata kaydında HTTP kodu ve yanıt gövdesi yazılı mı, yalnızca başarısız notu mu var?
• 429 ve 503 ayrı ele alınıyor, 400 ve 403 döngüden çıkarılıyor mu?
• Bekleme süresi her denemede artıyor ve rastgele pay içeriyor mu?
• Deneme sayısı üst sınırı ve hata kuyruğu tanımlı mı?
• Kayıt oluşturan isteklerde tekrarı tanıtan anahtar var mı?
• Sınıra yaklaşma durumu izlenip alarma bağlı mı?

KAV Yazılım, entegrasyonları bu yeniden deneme ve kuyruk düzeniyle kurar; sınır aşımı bir arıza değil, önceden tanımlanmış bir davranış olarak ele alınır.