سقف درخواست

برای اینکه API برای همه سریع بماند، تعداد درخواست‌ها در هر دقیقه محدود است.

سقف‌ها#

شمارش در پنجره‌های ثابت یک‌دقیقه‌ای انجام می‌شود که با شروع هر دقیقه ساعت (به وقت UTC) از صفر شروع می‌شوند. اگر کلیدتان به سقف بیشتری نیاز دارد، از صفحه تماس درخواست بدهید و کاربرد را توضیح دهید.

سرآیندهای پاسخ#

همه پاسخ‌های API، چه موفق و چه خطا، این سرآیندها را دارند:

HTTP/1.1 200 OK
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1793442120

وقتی سقف پر شود#

پاسخ با کد 429 و این بدنه برمی‌گردد:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "سقف درخواست در دقیقه پر شده است. پس از زمان Retry-After دوباره تلاش کنید"
  }
}

درخواستی که به ۴۲۹ خورده هم در شمارش حساب می‌شود، پس ارسال پشت سر هم فقط اوضاع را بدتر می‌کند. به اندازه Retry-After صبر کنید:

async function getJson(url, key, tries = 3) {
  for (let i = 0; i < tries; i++) {
    const res = await fetch(url, { headers: { Authorization: `Bearer ${key}` } });
    if (res.status !== 429) return res.json();
    const wait = Number(res.headers.get('Retry-After') ?? 5);
    await new Promise((r) => setTimeout(r, wait * 1000));
  }
  throw new Error('rate limited');
}

کم مصرف کردن#

• کش کنید. سرورها حدوداً هر یک دقیقه یک بار بررسی می‌شوند، پس خواندن وضعیت یک سرور بیشتر از دقیقه‌ای یک بار فایده‌ای ندارد. فیلد queriedAt زمان آخرین بررسی را نشان می‌دهد.
• از فهرست استفاده کنید. GET /servers وضعیت زنده هر سرور را هم برمی‌گرداند؛ برای نمایش ده سرور، یک درخواست فهرست بهتر از ده درخواست وضعیت است.
• وبهوک بگیرید. اگر فقط می‌خواهید از آفلاین شدن یا رکورد جدید باخبر شوید، به جای پرس‌وجوی مداوم وبهوک بسازید.
• برای سایت از ابزارک استفاده کنید. بنرها کش می‌شوند و از سهمیه شما کم نمی‌کنند.
• کلید را در سرور نگه دارید و پاسخ را برای بازدیدکنندگان سایتتان کش کنید، نه اینکه هر بازدید یک درخواست جدید بسازد.