محدودیت‌های نرخ و سهمیه‌ها#

دو محافظ مستقل بر هر درخواست API v2 و MCP اعمال می‌شود:

1. یک محدودکننده هجومی (burst limiter) سیل‌های کوتاه را پیش از هر کار دیتابیس متوقف می‌کند.
2. یک سهمیه تعداد درخواست‌هایی را که یک کاربر می‌تواند در روز و در ماه انجام دهد سقف‌گذاری می‌کند.

هر دو 429 با یک هدر Retry-After برمی‌گردانند، اما معنای متفاوتی دارند و باید متفاوت مدیریت شوند.

محدودکننده هجومی#

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

سهمیه#

سهمیه یک بار به ازای هر درخواست شارژ می‌شود، پس از بررسی هجومی و پس از اعتبارسنجی شعبه، و فراخوانی /api/v2/context را هم دربر می‌گیرد. /api/v2/health شارژ نمی‌شود.

ضریب‌های طرح#

یک طرح زمان‌محدود است. وقتی منقضی شود، طرح مؤثر به‌صورت خودکار به Free برمی‌گردد، بنابراین یکپارچه‌سازی‌ای که بر حدود Growth تکیه کرده بود دوباره 429 دریافت می‌کند.

پاسخ‌های محدودیت نرخ#

هجومی#

{
  "error": {
    "code": "api_burst_limit_exceeded",
    "message": "Too many API requests in a short period.",
    "retry_after_seconds": 17
  }
}

سهمیه#

{
  "error": {
    "code": "api_quota_exceeded",
    "message": "The API request quota has been reached.",
    "scope": "user",
    "period": "day",
    "limit": 200,
    "used": 200,
    "reset_at": "2026-11-01T00:00:00+04:30",
    "retry_after_seconds": 18234
  }
}

هر دو Retry-After را به‌صورت عدد صحیح ثانیه دربر دارند. به‌جای یک تاخیر ثابت از آن استفاده کنید.

پایش مصرف#

GET /api/v2/context طرح مؤثر، ضریب، منطقه زمانی و مصرف فعلی را برمی‌گرداند:

همان عددّها در کارت یکپارچه‌سازی‌ها در تنظیمات هم ظاهر می‌شوند.

طراحی درون حدها#

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

چه چیزی شمرده نمی‌شود#

• /api/v2/health.
• درخواست‌هایی که محدودکننده هجومی پیش از سهمیه‌شارژی آن‌ها را رد می‌کند.
• درخواست‌های ردشده برای یک خطای دامنه شعبه: اعتبارسنجی پیش از شارژ سهمیه انجام می‌شود و درخواست به‌صورت scope_denied ثبت می‌گردد.
• استفاده کارمندان از رابط وب.

نکات عملیاتی#

• درخواست‌های ردشده همچنان برای حسابرسی در لاگ رویداد درخواست نوشته می‌شوند، بدون افزایش سهمیه.
• last_used_at در احراز هویت موفق به‌روز می‌شود، نه در هر درخواست.
• یک تغییر طرح از درخواست بعدی اعمال می‌شود؛ هیچ استحقاق کش‌شده‌ای در توکن نیست.
• اگر دو یکپارچه‌سازی یک مالک مشترک داشته باشند، سهمیه را شریک‌اند. اگر جداسازی می‌خواهید مالک‌ها را تقسیم کنید.

صفحات مرتبط#

• خطاها
• احراز هویت
• کلیدهای API و دامنه‌های دسترسی
• شروع سریع