محدودیت نرخ و هدرها

Pitchbar محدودیت‌های نرخ را به ازای هر نقطه پایانی اعمال می‌کند تا از سوءاستفاده جلوگیری کند و هزینه‌های نقاط پایانی هزینه‌بر (هوش مصنوعی، جستجوی هوشمند) را قابل پیش‌بینی نگه دارد. هر پاسخ از یک سطح محدود به نرخ، یک مجموعه چهارگانه از هدرها را حمل می‌کند تا یکپارچه‌سازان بتوانند سرعت خود را تنظیم کنند.

هدرها در هر پاسخ

هدر	معنی
X-RateLimit-Limit	حداکثر درخواست‌های مجاز در پنجره فعلی.
X-RateLimit-Remaining	درخواست‌های باقی‌مانده در پنجره فعلی.
X-RateLimit-Reset	زمان‌مهر یونیکس زمانی که پنجره بازنشانی شده و بودجه بازیابی می‌شود.
Retry-After	فقط در پاسخ ۴۲۹ ارسال می‌شود — تعداد ثانیه‌هایی که باید قبل از تلاش مجدد صبر کرد.

میان‌افزار سطح API Pitchbar تضمین می‌کند که X-RateLimit-Reset در هر پاسخ ارسال می‌شود، نه فقط در ۴۲۹. این رفتار GitHub / Stripe را آینه می‌کند.

محدودکننده‌های نام‌گذاری‌شده در استفاده

محدودکننده	اعمال به	محدودیت	کلیدگذاری براساس
widget-init	POST /api/v1/widget/init	۱۰۰۰/دقیقه/IP+دستیار فروش · ۳۰۰۰۰/ساعت/IP	نرم به ازای هر IP — انفجارهای NAT را جذب می‌کند.
widget-session	POST /api/v1/widget/messages*، رویدادها، عملیات مکالمه	۳۰۰/دقیقه	به ازای هر JWT (جلسه بازدیدکننده).
widget-leads	POST /api/v1/widget/leads	۳۰/دقیقه	به ازای هر JWT.
wp-plugin	همه نقاط پایانی همگام‌سازی انبوه /v1/wp/*	۶۰/دقیقه	به ازای هر شناسه توکن API فضای کاری.
درون‌خطی (throttle:600,1)	POST /api/v1/widget/typing	۶۰۰/دقیقه/IP	به ازای هر IP (پینگ‌های تایپ بازدیدکننده).
درون‌خطی (throttle:60,1)	POST /api/v1/widget/satisfaction	۶۰/دقیقه/IP	به ازای هر IP.
درون‌خطی (throttle:120,1)	POST /api/v1/widget/coupon/apply	۱۲۰/دقیقه/IP	به ازای هر IP.

ظاهر ۴۲۹

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1747438932
Retry-After: 28

{"error":{"code":"rate_limited","message":"درخواست‌های ویجت زیادی برای این مکالمه وجود دارد. لطفاً سرعت خود را کاهش دهید."}}

بهترین روش‌ها برای مصرف‌کنندگان

• X-RateLimit-Remaining را در هر پاسخ بررسی کنید. وقتی به آستانه کوچکی رسید (مثلاً < ۵)، مکث کرده و منتظر X-RateLimit-Reset باشید.
• در ۴۲۹، به مدت مقدار Retry-After بخوابید و سپس دوباره تلاش کنید. به‌صورت نمایی عقب‌نشینی نکنید — پنجره قطعی است.
• اگر یکپارچه‌سازی با انشعاب بالا اجرا می‌کنید، فراخوان‌های خود را بخش‌بندی کنید تا همه یک IP مشترک نداشته باشند — سقف به ازای هر IP widget-init می‌تواند از یک خروجی واحد فشار زیادی وارد کند.