شروع کار

محدودیت نرخ

پنجره‌های محدودیت درخواست و توکن، سرآیندهای پاسخ و کاری که هنگام خطای 429 باید کرد.

محدودیت‌ها برای هر حساب اعمال می‌شود، نه برای یک کلید جدا. همه‌ی کلیدهای یک حساب از یک شمارنده مصرف می‌کنند. سقف مخصوص هر کلید روی آن، اضافه می‌شود.

پنجره‌ها

در هر درخواست این پنجره‌ها بررسی می‌شوند:

  • درخواست در دقیقه و توکن در دقیقه، از سطح API حساب. سطح بر اساس مجموع پرداخت‌های حساب تعیین می‌شود. برای بعضی مدل‌ها، سطح می‌تواند سقف دقیقه‌ای مخصوص همان مدل داشته باشد که جای سقف عمومی سطح را می‌گیرد.
  • درخواست در روز و توکن در روز، از همان سطح. روز به وقت تهران حساب می‌شود و نیمه‌شب تهران صفر می‌شود.
  • اگر برای کلید سقف تعیین کرده باشید: درخواست و توکن در دقیقه و در روز همان کلید.

مقدار سقف هر سطح و مدل در جدول صفحه‌ی /models (نمای جدول) و GET /api/public/api-tiers دیده می‌شود. پنجره‌ای که مقدار ندارد، سقفی ندارد.

همه‌ی پنجره‌ها با هم و یک‌جا بررسی می‌شوند. اگر یکی پر باشد، درخواست رد می‌شود و هیچ پنجره‌ای مصرف نمی‌کند.

توکن‌ها چگونه شمرده می‌شوند

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

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

این سرآیندها روی پاسخ موفق و پاسخ 429 هستند. مقدار از تنگ‌ترین پنجره‌ی دقیقه‌ای هر نوع می‌آید.

سرآیندمعنا
x-ratelimit-limit-requestsسقف درخواست در دقیقه
x-ratelimit-remaining-requestsدرخواست باقی‌مانده در این دقیقه
x-ratelimit-limit-tokensسقف توکن در دقیقه
x-ratelimit-remaining-tokensتوکن باقی‌مانده در این دقیقه
x-ratelimit-reset-requestsثانیه‌ی مانده تا شروع دقیقه‌ی بعد، مثل 23s
retry-afterفقط در 429، ثانیه تا اینکه دوباره بفرستید

اگر حسابی هیچ سقف دقیقه‌ای نداشته باشد، سرآیندهای مربوط به آن نوع نمی‌آیند. پنجره‌ی روزانه سرآیند جدا ندارد و فقط در خطا دیده می‌شود.

خطای 429

json
{
  "error": {
    "message": "Rate limit reached for requests per minute (limit 60). Please retry after 23s.",
    "type": "requests",
    "code": "rate_limit_exceeded",
    "param": null,
    "request_id": "6f1d3c52-8a0e-4b1e-9d7a-2f6f1c3b9a10"
  }
}

type برابر requests یا tokens است و پیام می‌گوید کدام پنجره (minute یا day) پر شده. مقدار 60 در بالا فقط یک نمونه است. retry-after برای پنجره‌ی دقیقه‌ای تا پایان همان دقیقه و برای پنجره‌ی روزانه تا نیمه‌شب تهران است.

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

  • budget_exceeded: بودجه‌ای که برای کلید، حساب، فضای کاری یا مدل تعریف شده پر شده است. با retry-after نمی‌آید و تا پایان دوره (روز، هفته یا ماه) یا تغییر بودجه باز نمی‌شود.
  • provider_rate_limit_exceeded: سرویس بالادستی موقتاً درخواست را نپذیرفت. اگر می‌توانست، دروازه خودش مسیر دیگری را امتحان کرده است.

رفتار پیشنهادی

  1. روی 429، به retry-after احترام بگذارید و بعد دوباره بفرستید. اگر نبود، با تأخیر نمایی.
  2. پیش از رسیدن به سقف، با x-ratelimit-remaining-* سرعت ارسال را کم کنید.
  3. درخواست‌های هم‌زمان را با یک صف محدود کنید. تلاش دوباره‌ی همه‌ی درخواست‌ها در یک لحظه، دوباره 429 می‌دهد.
  4. اگر مشکل پایدار است، سقف کلید را بالا ببرید (در محدوده‌ی سطح حساب) یا برای حجم بالا به پردازش دسته‌ای بروید.

اگر شمارنده در دسترس نباشد

اگر سرویس شمارنده در لحظه‌ای در دسترس نباشد، درخواست بدون بررسی این پنجره‌ها ادامه می‌یابد و سرآیندهای x-ratelimit-* نمی‌آیند.

صفحه‌های مرتبط