Rate Limits

Milagron API, anahtar bazında istek sınırlaması (rate limiting) uygular. Sınırın aşılması durumunda HTTP 429 yanıtı döner.

Varsayılan Limit

Her API anahtarı için varsayılan limit dakikada 60 istek olarak tanımlanmıştır. Bu değer, yönetim paneli üzerinden anahtar bazında 1 ile 10.000 arasında özelleştirilebilir.

Rate Limit Yanıtı

HTTP/1.1 429 Too Many Requests

{
  "error": "TooManyRequests",
  "message": "Rate limit exceeded"
}

Sliding Window

Limit hesaplaması sabit dakika aralıklarına değil, son 60 saniyelik kayan pencere (sliding window) yöntemine göre yapılmaktadır. Bu nedenle, ardışık dakikalarda dahi sınırın aşılma olasılığı bulunmaktadır.

Stage ve Production Ortamları

Rate limit, her iki ortamda da geçerlidir. Stage ortamında beklenmedik şekilde 429 yanıtı alınması durumunda aşağıdaki olasılıklar değerlendirilmelidir:

• Aynı anahtar üzerinden yüksek hızda yeniden deneme (retry) yapılıyor olabilir.
• Test amaçlı X-Stage-Force-Error: rate_limit header'ı her istekte 429 dönmesine yol açar.

Brute Force Koruması

Aynı IP adresinden 10 dakikalık dilim içerisinde 15 başarısız kimlik doğrulama denemesi gerçekleştirildiğinde, ilgili IP geçici olarak (10 dakika süreyle) bloklanır. Bu mekanizma rate limit'ten bağımsız çalışmakta olup, başarısız denemeler için ayrı bir sayım yapılmaktadır.

Önerilen Pratikler

Üstel Geri Çekilme (Exponential Backoff)

429 yanıtı alındığında anlık yeniden deneme yerine, beklemenin kademeli artırıldığı bir geri çekilme stratejisi izlenmelidir:

async function apiCallWithRetry(url, options, maxRetries = 5) {
    for (let attempt = 0; attempt < maxRetries; attempt++) {
        const res = await fetch(url, options);
        if (res.status !== 429) return res;

        const wait = Math.min(1000 * Math.pow(2, attempt), 30000);
        await new Promise(r => setTimeout(r, wait));
    }
    throw new Error('Rate limit exceeded after retries');
}

Toplu (Batch) İstekler

Tek bir ürün için ayrı ayrı çağrılar yerine, price-and-inventory endpoint'i ile tek istekte 1000 adede kadar item gönderilebilir. Bu yaklaşım hem performans hem de limit yönetimi açısından önerilmektedir.

Polling Sıklığı

Batch durum sorgulamaları için 2 saniyelik aralıkla başlanması ve toplam 60 saniyeyi aşmayacak şekilde polling yapılması önerilmektedir. Batch completed veya failed durumuna geçtiğinde polling sonlandırılmalıdır.