إنتقل إلى المحتوى الرئيسي

حدود المعدّل

الواجهة البرمجية العامة لمجيب محدودة المعدّل لكل مفتاح API. الافتراضي هو 60 طلباً في الدقيقة لكل مفتاح، مع عدّاد نافذة ثابتة تُعاد كل 60 ثانية.

ما الحد الافتراضي؟​

60 طلب في الدقيقة لكل مفتاح API. كل مفتاح له عدّاده الخاص — مفاتيح متعدّدة في نفس المنظمة لا تتشارك الميزانية. الطلب الذي يرفضه محدّد المعدّل لا يصل إلى خط الإرسال أبداً، لا يستهلك حصة، ولا يُنشئ محادثة.

هل يمكن الحصول على حد أعلى؟​

نعم. تجاوز الحد لكل مفتاح قابل للتهيئة من صفحة مفاتيح API في لوحة التحكم. إن احتجت حداً افتراضياً أعلى لتكامل عالي الحجم، تواصل مع الدعم مع معدّل الذروة المتوقَّع وحالة الاستخدام.

ماذا يحدث عند الوصول للحد؟​

تستجيب الواجهة بـ429 Too Many Requests، ظرف الخطأ القياسي، ورؤوس حد المعدّل الكاملة:

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

{
  "error": {
    "type":           "rate_limit_error",
    "code":           "rate_limit_exceeded",
    "message":        "Too many requests. Try again in 60 seconds.",
    "correlation_id": "req_01HQZ..."
  }
}
الرأسالمعنى
Retry-Afterثوانٍ للانتظار قبل الطلب التالي
X-RateLimit-Limitالحد المُهيَّأ في الدقيقة على هذا المفتاح
X-RateLimit-Remainingالطلبات المتبقية في النافذة الحالية — 0 عند الرفض
X-RateLimit-Resetطابع زمني Unix الذي تُعاد فيه النافذة

كيف ينبغي أن أتعامل مع استجابات 429؟​

احترم Retry-After. نَم لتلك الثواني على الأقل، ثم أعد نفس الطلب. إعادة المحاولة بعدوانية دون تأخّر ستبقيك مخنوقاً.

حلقة إعادة محاولة سليمة:

  1. أرسل الطلب
  2. إذا 429، استخرج Retry-After
  3. نَم لـRetry-After ثانية (بالإضافة إلى jitter صغير، مثل 0–2 ثانية عشوائياً، لتفادي إعادات قطيع الرعد من عملاء كُثر)
  4. أعد المحاولة — اقرن الإعادة بـIdempotency-Key الأصلي إن كنت استخدمته، حتى لا يُسبّب النجاح اللاحق إرسالاً مكرّراً

للحركة المستمرّة، نعّم معدّل إرسالك ليبقى تحت الحد بدلاً من الرشقات والتراجع — معدّل متوقَّع أفضل من خنق ارتجاعي.

هل توجد رؤوس على استجابات النجاح؟​

حالياً، لا. رؤوس X-RateLimit-* تُصدَر بشكل موثوق على رفض 429 فقط. رؤوس عدّاد على استجابات 2xx فجوة موثَّقة في v1 وستُسَدّ في إصدار لاحق. حتى ذلك الوقت، اعتمد على 429 + Retry-After لإشارات التراجع.

أسئلة شائعة​

هل ينطبق الحد على استعلامات الحالة؟​

نعم — الحد لكل مفتاح عبر كل نقاط /v1/، بما فيها GET /v1/whatsapp/messages/{id}. إن استعلمت بشكل متكرر عن حالات لرسائل كثيرة، احسب ذلك في ميزانيتك أو وزّع استعلامك.

ماذا يحدث إن كان لمنظمتي مفاتيح API متعدّدة؟​

كل مفتاح له ميزانيته المستقلّة. حد 60/دقيقة على المفتاح A لا يُنقص الطلبات المتاحة للمفتاح B. هذا يجعل من السهل إعطاء تكاملات مختلفة ميزانيات مستقلّة — مفتاح أتمتة تسويق يُستنفَد دون التأثير على مفتاح إشعارات معاملات.

هل يوجد سقف على مستوى المنظمة؟​

ليس في v1. عميل لديه 10 مفاتيح بـ60/دقيقة لكل واحد يمكنه نظرياً 600/دقيقة على مستوى المنظمة. قد نُضيف سقف على مستوى المنظمة في إصدار مستقبلي إن استدعى الأمر؛ ستُخطَر قبل أي تغيير.

ماذا لو استخدمت نفس المفتاح من خوادم متعدّدة؟​

الحد لكل مفتاح، وليس لكل خادم. الخوادم المتعدّدة المتشاركة لمفتاح واحد تتشارك الميزانية. لميزانيات مستقلّة عبر الخوادم، أصدر مفاتيح منفصلة.

هل يتفاعل حد ميتا لواتساب مع هذا؟​

نعم — حد مجيب لكل مفتاح منفصل عن حد ميتا لكل رقم عمل. إرسال يقبله مجيب (تحت ميزانية المفتاح) قد يُخنق أو يُرفَض من ميتا في المصب. خنق ميتا يظهر كـفشل تسليم على GET /v1/whatsapp/messages/{id}، وليس كـ429 منّا.