İadeler API'sinde Rate Limit (Hız Sınırı) Yönetimi

Her Ocak ayında destek kuyruğumuzda aynı ticket ortaya çıkıyor: 'İade entegrasyonumuz yıl boyunca sorunsuzdu, ayın ilk haftasında çöktü.' Genelde bir bug değil bu — trafik. Büyük alışveriş dönemlerinin ardından gelen haftalarda iade hacimleri sert bir şekilde yükseliyor ve Kasım ayında dakikada 200 isteği rahatça karşılayan bir iade API'si, bir anda dakikada 2.000 istek almaya başlayabiliyor. Entegrasyonunuz sabit bir yük varsayımıyla kurulduysa, rate limit'ler kenar durumdan kesintiye dönüşüyor.

Bu yazı, hacim zirveleri en sert vurduğunda bir iade API entegrasyonunu sağlıklı tutmak için pratik bir rehber — backoff, batching ve kuyruklamanın mekaniği, ayrıca bir mağazanın iade akışının isteklerini sessizce düşürmek yerine çalışmaya devam etmesini sağlayan operasyonel alışkanlıklar. İade platformuna bağlanmanın temellerinden henüz geçmediyseniz, verimlilik sorunlarına girmeden önce iade API entegrasyon rehberimize göz atın.

Rate limit'ler neden en çok iade zirvelerinde ısırıyor

Rate limit'ler paylaşılan altyapıyı korumak için var — bir istemcinin belirli bir zaman penceresinde gönderebileceği istek sayısını, genellikle saniye veya dakika başına istek olarak sınırlıyorlar. Normal yükte çoğu mağaza bunları hiç fark etmez. Ama iade trafiği alışılmadık şekilde patlamalı: gün boyu yayılan gezinme veya ödeme trafiğinin aksine, iade başlatma belirli tetikleyiciler etrafında sıkı sıkı kümeleniyor — tatil sonrası Pazartesi, iade süresinin dolduğu gün ya da flaş satış sonrası ertesi gün. NRF verilerine göre perakendeciler tatil satışlarının yaklaşık %17'sinin iade edilmesini bekliyor ve bu hacim eşit dağılmıyor. Genellikle iki saatlik bir pencerede, müşteriler gelen kutularını açıp toplu halde iade talebi başlattığında geliyor.

Sipariş durumunu sorgulayan, iade etiketi oluşturan ve her istek için envanteri senkron güncelleyen bir iade API entegrasyonu, işletmenin güvenilirliğe en çok ihtiyaç duyduğu anda 429 (Too Many Requests) yanıtlarıyla karşılaşmaya başlar. Daha kötüsü, saf bir retry döngüsü — limite çarp, bir saniye bekle, hemen tekrar dene — o endpoint'i paylaşan diğer istemciler için sorunu daha da kötüleştiren bir retry fırtınası yaratabilir.

Üç sütun: backoff, batching ve kuyruklama

1. Jitter'lı üstel geri çekilme (exponential backoff)

En yüksek etkili düzeltme, sabit aralıklı retry'leri jitter'lı üstel geri çekilme ile değiştirmektir. Her saniye tekrar denemek yerine, her başarısız denemeden sonra bekleme süresini iki katına çıkarın (1sn, 2sn, 4sn, 8sn...) makul bir tavana kadar ve eşzamanlı retry yapan birden fazla istemcinin aynı anda API'ye saldırmaması için küçük rastgele bir ofset ekleyin. Çoğu iade API yanıtı 429'larda `Retry-After` header'ı içerir — bunu bir öneri değil bir taban olarak kabul edin ve tekrarlayan hatalar için üzerine kendi backoff'unuzu ekleyin.

• Toplam retry deneme sayısına üst sınır koyun (tipik olarak 5-8) ve sonrasında zarifçe bir dead-letter kuyruğuna düşürün
• Retry-After header'larına tam uyun; daha kısa bir aralık tahmin etmeyin
• Worker filonuzda senkronize retry sıçramalarından kaçınmak için %20-30 jitter ekleyin
• Her 429'u zaman damgası ve endpoint ile loglayın, böylece kalıpları kesintiye dönüşmeden görebilirsiniz

Retry'ler tek başına eksiksiz bir strateji değil — tekrarlanan bir isteğin yinelenen bir iade oluşturmasını veya müşteriye çift iade yapmasını önlemek için idempotency ile eşleştirilmeleri gerekiyor. Detayları iade API idempotency ve retry rehberimizde ele alıyoruz; retry mantığınızı büyütmeden önce uygulamaya değer.

2. Tek tek çağrılar yerine istekleri toplu (batch) gönderin

Birçok entegrasyon her iade olayını kendi API çağrısı gibi ele alma hatasına düşer: sipariş detayı için bir çağrı, uygunluk doğrulaması için bir çağrı, etiket oluşturma için bir çağrı, envanter güncellemesi için bir çağrı. Bir zirve sırasında bu, aynı iş sonucu için dört kat istek hacmi demek. ResReturn dahil çoğu iade platformu tam olarak bunun için batch endpoint'leri sunar — tek bir çağrıda 50 veya 100 iade kaydı gönderin ve platformun bunları sunucu tarafında işlemesine izin verin. Batching, rate limit tavanınıza karşı faturalandırılabilir istek sayısını büyük ölçüde azaltır ve genellikle toplam işlem gecikmesini de kısaltır, çünkü platform istemcinizin gidiş-dönüşleri beklemesi yerine dahili olarak paralelleştirebilir.

3. İstemci tarafında kuyruklayın ve kısıtlayın

En dayanıklı entegrasyonlar iade API'sini doğrudan bir web istek işleyicisinden çağırmaz. İade olaylarını dahili bir kuyruğa (SQS, RabbitMQ veya basit bir veritabanı destekli iş tablosu) iterler ve bu kuyruğu kontrollü bir hızda tüketen bir worker havuzu bulundururlar — API'nin yayınlanmış rate limitine uyacak şekilde, aynı API anahtarını paylaşan diğer trafik için de boşluk bırakarak. Bu, müşteriye dönük gecikmeyi (iade gönderen bir alışverişçi anında bir onay görür) arka plan işleme hızından ayırır ve limitler değiştiğinde ayarlayabileceğiniz tek bir kısıtlama noktası verir.

Ocak ayını atlatan entegrasyonlar en akıllı retry mantığına sahip olanlar değil — hiç retry'e ihtiyaç duymayanlar, çünkü kendi trafiklerini API'ye çarpmadan önce kendileri düzleştirdiler.

Zirve sezon için rate limit bütçenizi ölçeklendirmek

Zirve sezon başlamadan önce, beklenen iade hacminizi API katmanınızın limitlerine karşı modelleyin. Yararlı bir alıştırma: günlük ortalama iade hacminizi alın, kategorinizin tipik olarak gördüğü zirve/ortalama oranıyla çarpın (giyim ve ayakkabıda genellikle 2-4 kat) ve mevcut planınızın ve batching stratejinizin bu tavanı marjla karşılayıp karşılamadığını kontrol edin. Bu, zirve sezon iade operasyonları rehberimizdeki operasyonel oyun kitabıyla doğrudan eşleşir — rate limit planlaması aslında daha geniş zirve hazırlığının bir alt kümesidir.

İzleme: sorunu müşteriden önce yakalayın

Rate limit sorunları öyle olana kadar sessizdir — başarıyla tekrar denenen bir 429 hiçbir zaman müşteriye görünmez, ama dashboard'larınız 429 oranlarını öncü bir gösterge olarak takip etmiyorsa, gerçek bir sorunu ancak iadeler gecikmeye başladığında veya destek kuyruğu dolduğunda öğrenirsiniz. Bunları sadece hata logu olarak değil, birinci sınıf metrik olarak takip edin:

1. 1Toplam isteklerin yüzdesi olarak 429 yanıt oranı, %1 ve %5 eşiklerinde alarm
2. 2İade worker kuyruğunuzdaki kuyruk derinliği ve işlenmemiş en eski öğenin yaşı
3. 3İade gönderiminden etiket oluşturmaya P95 süresi, bilinen zirve pencerelerinde sapma için izlenmeli
4. 4Retry tükenme sayısı — maksimum retry'e ulaştıktan sonra dead-letter kuyruğuna düşen öğeler

Backoff ve batching'i uyguladıktan sonra bile sürekli 429 görüyorsanız, bu platformunuzla geçici veya kalıcı limit artışı konuşma zamanı olduğunun sinyalidir — ResReturn dahil çoğu sağlayıcı, beklenen bir hacim zirvesini (bir ürün lansmanı, bilinen bir tatil sonrası pencere veya bir pazarlama hamlesi) tepki vermeden birkaç gün önceden işaretlerseniz proaktif olarak limitleri artırabilir.

Sıkça Sorulan Sorular