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

حدود المعدّل

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

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

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

هل لبعض نقاط النهاية حد أقل؟​

نعم. عرض قوالب واتساب، GET /v1/agents/{agentId}/connections/{connectionId}/whatsapp-templates، يُعيد ما يقرؤه مباشرة من ميتا، لذا يسمح بـ 10 طلبات في الدقيقة لكل مفتاح، في ميزانية خاصة به: استدعاءاته لا تستهلك الـ60 الخاصة بك، واستدعاءاتك الأخرى لا تستهلك الـ10 الخاصة به. والرد في محادثة، POST /v1/agents/{agentId}/conversations/{conversationId}/messages، يسمح بـ 20 طلباً في الدقيقة لكل مفتاح (يُحسب كل استدعاء له، ومنه الإعادات و409 والردود المرفوضة)، في ميزانية خاصة به أيضاً: كل رد يصل إلى عميل ويوقف الذكاء الاصطناعي، فللإرسال مساحة أقل من القراءة، ولا تنتظر قراءاتك إرسالك أبداً. راجع المحادثات والرسائل. ولاختبار أدوات ربط نظامك أيضاً حد لشركتك كلها، 30 اختباراً في الدقيقة عبر مفاتيحها ولوحة التحكم (429 test_rate_limited)، فوق ميزانية مفتاحك؛ راجع أدوات ربط نظامك.

تعرض صفحة كلٍّ منها في المرجع حدها في x-rate-limit-per-minute، ويُبلغ الرد 429 منها به في X-RateLimit-Limit. ويحمي حد عرض القوالب حصة رقم واتساب لدى ميتا، وهي ما يعتمد عليه إرسالك: احتفظ بالقائمة بدلاً من قراءتها قبل كل إرسال، واقرأها مجدداً بعد أن تتغيّر قوالبك. فكل إرسال لقالب يقرأ قوالب الرقم من ميتا أصلاً ليتحقّق من الاسم واللغة، فعرض القائمة قبل كل إرسال يضاعف هذه القراءات. راجع عرض قوالب واتساب.

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

ليس من لوحة التحكم. كل مفتاح يحصل اليوم على 60 طلباً في الدقيقة، و10 على عرض القوالب، و20 على الردود. إن احتاج تكامل عالي الحجم أكثر من ذلك، تواصل مع الدعم مع معدّل الذروة المتوقَّع وحالة الاستخدام.

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

تستجيب الواجهة بـ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حد الدقيقة لنقطة النهاية التي استدعيتها (60، أو 10 على عرض القوالب، أو 20 على الردود)
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}؛ ولا يُحسب منفصلاً إلا عرض القوالب والردود في المحادثات. إن استعلمت بشكل متكرر عن حالات لرسائل كثيرة، احسب ذلك في ميزانيتك أو وزّع استعلامك. أما GET /v1/openapi.yaml فلا يحتاج مفتاحاً ويُحَد لكل عنوان IP.

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

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

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

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

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

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

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

نعم — حد مجيب لكل مفتاح منفصل عن حد ميتا لكل رقم عمل. إرسال يقبله مجيب (تحت ميزانية المفتاح) قد يُخنق أو يُرفَض من ميتا في المصب. خنق ميتا لا يظهر أبداً كـ429 منّا؛ بل يظهر على GET /v1/whatsapp/messages/{id} كـstatus: failed. للقالب، ولأي رسالة تُفشلها ميتا بعد قبولها، تكون failure_reason هي RateLimited ويحمل failure_code رمز ميتا (مثل 130429 و131056). أما النص الحر الذي ترفضه ميتا لحظة الإرسال فيظهر حالياً بـfailure_reason: Unknown دون failure_code، أياً كان السبب. وحين تخنق ميتا عرض القوالب نفسه، يُعيد 503 meta_unavailable: أعد المحاولة بتراجع متصاعد.