محدودیت نرخ (rate limiting)

مقادیر پیش‌فرض

هر کلید وب‌سرویس به‌طور پیش‌فرض ۲۰ درخواست در دقیقه را پردازش می‌کند. این محدودیت بر اساس کلید (نه بر اساس IP) اعمال می‌شود؛ یعنی چندین سرور با یک کلید مجموعاً همان سقف را به اشتراک می‌گذارند.

افزایش سقف

می‌توانید در زمان ساخت کلید (یا بعداً در داشبورد) سقف بالاتری تعیین کنید. اشتراک‌های فعال نیز سقف وب‌سرویس را به‌صورت خودکار افزایش می‌دهند.

پاسخ هنگام عبور از سقف

اگر از سقف عبور کنید، سرور پاسخ 429 Too Many Requests برمی‌گرداند. هدر Retry-After مشخص می‌کند چند ثانیه دیگر می‌توانید درخواست بعدی را ارسال کنید.

HTTP/1.1 429 Too Many Requests
Retry-After: 7
Content-Type: application/json

{"detail":"Request was throttled. Expected available in 7 seconds."}

الگوی توصیه‌شده: exponential backoff

در صورت دریافت 429، چند ثانیه صبر کنید (مقدار Retry-After) و درخواست را تکرار کنید. اگر باز هم 429 گرفتید، فاصله را دو برابر کنید (۲، ۴، ۸ ثانیه…) تا حداکثر ۶۰ ثانیه.

async function callWithBackoff(url, options, maxAttempts = 5) {
  let attempt = 0
  let delay = 1000 // ms
  while (attempt < maxAttempts) {
    const res = await fetch(url, options)
    if (res.status !== 429) return res

    const retryAfter = Number(res.headers.get('Retry-After')) || delay / 1000
    await new Promise((r) => setTimeout(r, retryAfter * 1000))
    delay = Math.min(delay * 2, 60000)
    attempt += 1
  }
  throw new Error('rate limit exceeded after retries')
}