قرارداد محدودیت نرخ API
سقف فراخوانی هر نقطه پایانی عمومی مکس‌پوینت، پنجره زمانی و هدرهای استاندارد پاسخ
429 Too Many Requests — برای توسعه‌دهندگان و یکپارچه‌سازان.
فعال
بدون نیاز به تنظیمات
به‌روزرسانی: ۲۰۲۶-۱۱-۰۱
سقف‌های اعمال‌شده
محدودیت‌ها بر پایه IP + مسیر اعمال می‌شوند (کلید کلاینت از
REMOTE_ADDR یا اولین هاپ X-Forwarded-For).
با رسیدن به سقف، پاسخ 429 بازگردانده می‌شود و کد کنترلر هرگز اجرا نمی‌شود.
| نقطه پایانی | سقف | پنجره | دامنه | توضیح |
|---|---|---|---|---|
POST
/api/auth/register
|
۱۰ بار | هر ۱ دقیقه | هر IP | ثبت‌نام |
POST
/api/auth/login
|
۱۰ بار | هر ۱ دقیقه | هر IP | ورود با رمز |
POST
/api/auth/send-code
|
۶ بار | هر ۱ دقیقه | هر IP | ارسال کد یک‌بارمصرف — پرتکرارترین سطح سوءاستفاده |
POST
/api/auth/callback/credentials
|
۱۰ بار | هر ۱ دقیقه | هر IP | ورود با اعتبارنامه |
POST
/api/auth/signin
|
۱۰ بار | هر ۱ دقیقه | هر IP | ورود |
POST
/api/admin/settings/unlock
|
۵ بار | هر ۱۰ دقیقه | هر حساب | قفل تنظیمات — علاوه بر محدودیت مسیر (۱۰ در دقیقه)، پنجره ضدحمله رایو برای هر حساب |
POST
/api/admin/ai/process-exam/{attemptId}
|
۳۰ بار | هر ۱ ساعت | هر IP | تحلیل هوش مصنوعی آزمون — سقف روزانه بودجه AI نیز جداگانه اعمال می‌شود |
POST
/api/admin/ai/recommendations/{userId}
|
۳۰ بار | هر ۱ ساعت | هر IP | توصیه‌های هوش مصنوعی — همان بودجه |
POST
OTP verify
|
۱۰ بار | هر ۱۰ دقیقه | حساب + IP | بررسی کد یک‌بارمصرف — ۲۰ تلاش از هر IP نیز سقف دارد |
هدرهای پاسخ 429
هر پاسخ 429 این هدرهای استاندارد را حمل می‌کند؛ کتابخانه کلاینت باید پیش از تلاش مجدد، Retry-After را رعایت کند.
HTTP/1.1 429 Too Many Requests
Retry-After: 56
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1789362697Retry-After— ثانیه تا پذیرش درخواست بعدی (همیشه ≥ ۱).X-RateLimit-Limit— سقف پیکربندی‌شده پنجره.X-RateLimit-Remaining— روی درخواست رد‌شده همیشه صفر.X-RateLimit-Reset— زمان انقضای کل پنجره (یونیکس).
نکات فنی
- درخواست‌های مجاز هیچ هدر اضافه‌ای حمل نمی‌کنند — تزئین 429 فقط روی پاسخ رد‌شده است.
- محاسبه هدرها best-effort است؛ خرابی فایل شمارشگر هرگز یک 429 را به خطای 500 تبدیل نمی‌کند.
- شمارشگرها بیرون از ریشه وب ذخیره می‌شوند و سطل‌های منقضی به‌طور احتمالاتی پاک‌سازی می‌شوند.
- سقف‌ها مقادیر پیش‌فرض کد هستند؛ برای تغییر یک مسیر،
->throttle(N, M)همان مسیر تغییر می‌کند.