رموز الخطأ في API السحابة
تم تطوير API السحابة استنادًا إلى Graph API، لذلك إذا كان التعامل مع استجابات الأخطاء في Graph API غير مألوف، فيمكنك الرجوع إلى وثائق معالجة الخطأ في Graph API.
بشكل عام، نوصي بإنشاء منطق معالجة الخطأ في تطبيقك ليعتمد على قيم code وخصائص حمولة البيانات details. تشير هذه الخصائص وقيمها بشكل أكبر إلى الخطأ الأساسي.
يتم تضمين عناوين الرموز، التي لا تحتوي على خاصية مخصصة في حمولات بيانات استجابة الأخطاء في API، كجزء من قيمة message. مع ذلك، نوصي بعدم الاعتماد على العناوين في منطق معالجة الأخطاء حيث سيتم إيقاف استخدام العناوين في النهاية.
تلقي الأخطاء: المتزامنة وغير المتزامنة
يتم إرجاع أخطاء API السحابة إما بشكل متزامن كاستجابة Graph API أو بشكل غير متزامن عبر حدث Webhook أو في بعض الأحيان عبر كلا الأسلوبين.
عند العمل مع API السحابة يُعد مراقبة كل من استجابة Graph API وحدث webhook messages ممارسة جيدة لمعالجة الخطأ. إذا كنت مشترك في حقل حدث webhook messages، فستتلقى إشعارًا بالأخطاء بينما تحدث لأنواع الأخطاء غير المتزامنة المدعومة.
أحداث Webhooks وبنية استجابة الخطأ
يمكن عرض أخطاء API السحابة في كائنات حدث webhook التالية:
API السحابة
entry.changes.value.errorsentry.changes.value.messages.errors
API داخل المواقع
errors
بنية استجابة الخطأ
{
"error": {
"message": "<MESSAGE>",
"type": "<TYPE>",
"code": <CODE>,
"error_data": {
"messaging_product": "whatsapp",
"details": "<DETAILS>"
},
"error_subcode": <ERROR_SUBCODE>
"fbtrace_id": "<FBTRACE_ID>"
}
}محتويات استجابة الخطأ
| الخاصية | نوع القيمة | الوصف |
|---|---|---|
| Integer (عدد صحيح) | رمز الخطأ. نوصي بإنشاء منطق معالجة الأخطاء في تطبيقك ليعتمد على رموز الأخطاء بدلاً من الرموز الفرعية أو رموز حالة استجابة HTTP. |
| String (سلسلة) | وصف الخطأ ووصف السبب الأكثر ترجيحًا لحدوث الخطأ. قد تحتوي أيضًا على معلومات حول كيفية معالجة الخطأ، مثل المعلمة غير الصالحة أو القيم المقبولة. |
| Integer (عدد صحيح) | تم إيقاف الاستخدام. ولن يتم إرجاعه في استجابات الإصدار 16.0 والإصدارات الأحدث. الرمز الفرعي لـ Graph API. لن تتضمن كل الاستجابات رمزًا فرعيًا، لذلك نوصي بإنشاء منطق معالجة الخطأ بحيث يعتمد على الخاصيتين |
| String (سلسلة) | معرف التتبع الذي يمكنك تضمينه عند التواصل مع الدعم المباشر. وقد يساعدنا المعرف في تصحيح الأخطاء. |
| String (سلسلة) | مجموعة من رموز الأخطاء وعناوينها. على سبيل المثال: |
| String (سلسلة) | منتج المراسلة. ستمثل هذه الخاصية دائمًا سلسلة |
| String (سلسلة) | نوع الخطأ. |
عينة من الاستجابة
{
"error": {
"message": "(#130429) Rate limit hit",
"type": "OAuthException",
"code": 130429,
"error_data": {
"messaging_product": "whatsapp",
"details": "Message failed to send because there were too many messages sent from this phone number in a short period of time"
},
"error_subcode": 2494055,
"fbtrace_id": "Az8or2yhqkZfEZ-_4Qn_Bam"
}
}
رموز الأخطاء
أخطاء التصريح
| الرمز | الوصف | الحلول المحتملة | رمز حالة HTTP |
|---|---|---|---|
AuthException | تتعذر مصادقة مستخدم التطبيق. | عادةً ما يعني ذلك أن رمز الوصول المضمن قد انتهت صلاحيته أو أصبح غير صالح أو أن مستخدم التطبيق قد قام بتغيير الإعداد لمنع جميع التطبيقات من الوصول إلى بياناته. نوصي بالحصول على رمز وصول جديد. |
غير مصرح به |
أسلوب API | توجد مشكلة في الإمكانية أو الأذونات. | استخدم أداة تصحيح أخطاء رمز الوصول للتحقق من منح تطبيقك الأذونات المطلوبة بواسطة نقطة النهاية. راجع استكشاف الأخطاء وإصلاحها. |
خطأ داخلي بالخادم |
تم رفض الإذن | لم يتم منح الإذن أو تمت إزالته. | استخدم أداة تصحيح أخطاء رمز الوصول للتحقق من منح تطبيقك الأذونات المطلوبة بواسطة نقطة النهاية. راجع استكشاف الأخطاء وإصلاحها. تأكد من أن رقم الهاتف المستخدم في إعداد مفتاح النشاط التجاري العام مدرج في قائمة السماح. |
ممنوع |
انتهت صلاحية رمز الوصول | انتهت صلاحية رمز الوصول. |
غير مصرح به | |
إذن API | لم يتم منح الإذن أو تمت إزالته. | استخدم أداة تصحيح أخطاء رمز الوصول للتحقق من منح تطبيقك الأذونات المطلوبة بواسطة نقطة النهاية. راجع استكشاف الأخطاء وإصلاحها. |
محظور |
تقييد الأخطاء
| الرمز | الوصف | الحلول المحتملة | رمز حالة HTTP |
|---|---|---|---|
استدعاءات كثيرة للغاية لواجهة API | وصل التطبيق إلى تقييد معدلات استدعاء API. | يمكنك تحميل التطبيق في لوحة معلومات التطبيق وعرض قسم تقييد معدلات استدعاء التطبيق للتحقق من وصول التطبيق إلى تقييد معدلات الاستدعاء. إذا وصل بالفعل إلى التقييد المحدد، فحاول مرة أخرى لاحقًا أو يمكنك تقليل التكرار أو مقدار استعلامات API التي يقوم بها التطبيق. |
طلب غير صالح |
مشاكل تقييد معدلات الاستدعاء | قد وصل حساب واتساب للأعمال إلى تقييد معدلات الاستدعاء المخصص له. | راجع تقييدات معدلات الاستدعاء في حساب واتساب للأعمال. حاول مرة أخرى لاحقًا أو يمكنك تقليل التكرار أو مقدار استعلامات API التي يقوم بها التطبيق. |
طلب غير صالح |
تم الوصول إلى تقييد معدلات الاستدعاء | تم الوصول إلى معدل إرسال رسالة API السحابة المسموح به. | لقد وصل التطبيق إلى تقييد معدل الإرسال المسموح به في API. راجع معدل الإرسال. حاول مرة أخرى لاحقًا أو يمكنك تقليل معدل تكرار إرسال التطبيق للرسائل. |
طلب غير صالح |
تم الوصول إلى تقييد معدلات الاستدعاء المخصص للمحتوى غير المهم أو الاحتيالي | تعذر إرسال الرسالة نظرًا إلى وجود تقييدات على عدد الرسائل التي يمكن إرسالها من رقم الهاتف هذا. وقد يرجع ذلك إلى حظر عدد كبير من الرسائل السابقة أو الإبلاغ عنها باعتبارها محتوى غير مهم أو احتيالي. | تحقق من حالة الجودة لديك في مدير واتساب وراجع وثائق تقييدات معدلات الاستدعاء المستندة إلى الجودة لمزيد من المعلومات. |
طلب غير صالح |
تم الوصول إلى تقييد معدلات الاستدعاء المخصص للإقران (حساب الأعمال، حساب المستهلك) | تم إرسال عدد كبير جدًا من الرسائل من رقم هاتف المرسل إلى رقم هاتف المستلم ذاته ضمن فترة زمنية قصيرة. | انتظر ثم أعد العملية، إذا كنت تنوي إرسال رسائل إلى رقم الهاتف ذاته. لا يزال بإمكانك إرسال رسائل إلى رقم هاتف مختلف من دون الحاجة إلى الانتظار |
طلب غير صالح |
تم تجاوز تقييد معدل استدعاء تسجيل الحساب | فشل التسجيل أو إلغاء التسجيل نظرًا إلى وجود عدد كبير جدًا من المحاولات لرقم الهاتف هذا في فترة زمنية قصيرة | يتم حظر رقم هاتف النشاط التجاري لأنه وصل إلى الحد الأقصى المسموح به لمحاولات التسجيل/إلغاء التسجيل. حاول مرة أخرى بمجرد إلغاء حظر الرقم. راجع "التقييدات" في مستند التسجيل. |
طلب غير صالح |
أخطاء Integrity
| الرمز | الوصف | الحلول المحتملة | رمز حالة HTTP |
|---|---|---|---|
تم الحظر مؤقتًا نتيجة انتهاك السياسات | تم تقييد حساب واتساب للأعمال المرتبط بالتطبيق أو تعطيله نتيجة انتهاك سياسة المنصة. | راجع مستند إنفاذ السياسة للتعرف على انتهاكات السياسة وكيفية حلها. |
ممنوع |
تم تقييد حساب الأعمال من مراسلة المستخدمين في هذا البلد. | يتم تقييد حساب واتساب للأعمال من إرسال الرسائل إلى المستخدمين في بلدان معينة. | انظر سياسة مراسلات الأعمال في واتساب للحصول على تفاصيل حول البلدان المسموح بها للمراسلة في فئة نشاطك التجاري. |
ممنوع |
تم قفل الحساب | تم تقييد حساب واتساب للأعمال المرتبط بالتطبيق أو تعطيله نتيجة انتهاك سياسة المنصة أو أنه يتعذر علينا التحقق من صحة البيانات المضمنة في الطلب مقابل مجموعة البيانات المتوفرة في حساب واتساب للأعمال (على سبيل المثال قد يكون رقم التعريف الشخصي للتحقق بخطوتين المضمَّن في الطلب غير صحيح). | راجع مستند إنفاذ السياسة للتعرف على انتهاكات السياسة وكيفية حلها. يمكنك أيضًا استخدام API حالة الحساب، والتي قد توفر نظرة إضافية عن أسباب قفل الحساب. |
ممنوع |
الأخطاء الأخرى
| الرمز | الوصف | الحلول المحتملة | رمز حالة HTTP |
|---|---|---|---|
API مجهولة | يوجد طلب غير صالح أو خطأ محتمل في الخادم. | اطلع على صفحة حالة منصة واتساب للأعمال للتعرف على معلومات حول حالة API. إذا لم يكن هناك حالات انقطاع في الخادم، فيمكنك الرجوع إلى مرجع نقطة النهاية والتحقق من تنسيق طلبك بشكل صحيح وأنه يفي بكل متطلبات نقطة النهاية. |
طلب غير صالح |
خدمة API | مؤقتة بسبب زمن التوقف أو بسبب التحميل الزائد. | اطلع على صفحة حالة منصة واتساب للأعمال للتعرف على معلومات حول حالة API قبل إعادة المحاولة. |
الخدمة غير متوفرة |
قيمة المعلمة غير صالحة | تم حذف رقم هاتف النشاط التجاري. | تحقق من أن رقم هاتف النشاط التجاري صحيح. |
طلب غير صالح |
معلمة غير صالحة | يتضمن الطلب معلمة واحدة أو أكثر غير مدعومة أو بها أخطاء إملائية. | راجع مرجع نقطة النهاية لتحديد المعلمات المدعومة وكيفية تهجئتها. احرص عند تعيين المفتاح العام للنشاط التجاري، أن يكون مفتاح عام بتنسيق 2048-bit RSA. تأكد من عدم تطابق معرف رقم الهاتف الذي تعمل على تسجيله ومعرف رقم الهاتف المخزن مسبقًا. تأكد من أن المعلمة تخضع لأي قيود بخصوص المدة بالنسبة للنوع. |
طلب غير صالح |
رقم المستخدم يمثل جزءًا من تجربة | لم يتم إرسال الرسالة كجزء من التجربة. | راجع تجربة الرسالة التسويقية. |
طلب غير صالح |
حدث خطأ ما | تعذّر إرسال الرسالة نتيجة خطأ غير معروف. عند تعيين مفتاح عام للنشاط التجاري، يتعذر حينها حساب التوقيع أو استدعاء نقطة نهاية GraphQL أو تقوم نقطة نهاية GraphQL بإرجاع خطأ. | حاول مرة أخرى. إذا استمر الخطأ، فافتح تذكرة دعم مباشر. |
خطأ داخلي بالخادم |
الوصول مرفوض | لم يتم منح الإذن أو تمت إزالته. | استخدم أداة تصحيح أخطاء رمز الوصول للتحقق من منح تطبيقك الأذونات المطلوبة بواسطة نقطة النهاية. راجع استكشاف الأخطاء وإصلاحها. |
ممنوع |
المعلمة المطلوبة غير موجودة | يفتقد الطلب إلى معلمة مطلوبة. | راجع مرجع نقطة النهاية لتحديد المعلمات المطلوبة. |
طلب غير صالح |
قيمة المعلمة غير صالحة | قيم معلمة واحدة أو أكثر غير صالحة. | راجع مرجع نقطة النهاية لتحديد القيم المدعومة لكل معلمة، وراجع أرقام الهواتف للتعرف على كيفية إضافة رقم هاتف إلى حساب واتساب للأعمال. |
طلب غير صالح |
الخدمة غير متوفرة | الخدمة غير متوفرة مؤقتًا. | اطلع على صفحة حالة منصة واتساب للأعمال للتعرف على معلومات حالة API قبل إعادة المحاولة. |
خطأ داخلي بالخادم |
لا يمكن أن يكون المستلم هو المرسل نفسه | رقم هاتف المرسل هو ذاته رقم المستلم. | أرسل رسالة إلى رقم هاتف آخر بخلاف رقم المرسل. |
طلب غير صالح |
تعذر إرسال الرسالة | تعذر تسليم الرسالة. يمكن أن تتضمن الأسباب:
| باستخدام وسيلة اتصال بخلاف واتساب، اطلب من مستخدم واتساب:
|
طلب غير صالح |
مشكلة في الدفع تتعلق بأهلية النشاط التجاري | حدث خطأ متعلق بطريقة الدفع. | راجع حول الفوترة في حساب واتساب للأعمال وتحقق من إعداد الفوترة بشكل صحيح. المشكلات الشائعة:
|
طلب غير صالح |
شهادة غير صحيحة | فشل إرسال الرسالة بسبب خطأ في تسجيل رقم الهاتف. | يمكنك تسجيل رقم الهاتف قبل إعادة المحاولة. |
خطأ داخلي بالخادم |
رسالة تشجيع التفاعل | لقد مرت أكثر من 24 ساعة منذ تلقي آخر رد من جانب المستلم على رقم المرسل. | أرسل للمستلم رسالة بدأها النشاط التجاري باستخدام قالب رسالة بدلاً من ذلك. |
طلب غير صالح |
اختارت Meta عدم التسليم. | لم يتم تسليم هذه الرسالة للحفاظ على أداء التفاعل داخل النظام. | لا تحاول مرة أخرى على الفور إذا تلقيت رمز الخطأ هذا وكنت تشتبه في أن ذلك نتيجة التقييد. بدلاً من ذلك، أعد المحاولة عن طريق توفير زيادات زمنية أكبر حتى يتم توصيل الرسالة، لأن التقييد قد يكون ساريًا لفترات زمنية مختلفة. راجع تقييدات رسائل قالب التسويق لكل مستخدم للحصول على معلومات إضافية. |
طلب غير صالح |
نوع الرسالة غير مدعوم | نوع الرسالة غير مدعوم. | راجع الرسائل للتعرف على أنواع الرسالة المدعومة قبل إعادة المحاولة باستخدام نوع رسالة مدعوم. |
طلب غير صالح |
خطأ في تنزيل الوسائط | تعذر تنزيل الوسائط المرسلة من جانب المستخدم. | تعذر تنزيل الوسائط المتضمنة في رسالة مستخدم واتساب. لمزيد من المعلومات، راجع القيمة اطلب من مستخدم واتساب إرسال ملف الوسائط بطريقة أخرى بخلاف واتساب. |
طلب غير صالح |
خطأ في تحميل الوسائط | تعذر تحميل الوسائط المستخدمة في الرسالة. | تعذر علينا تحميل الوسائط لسبب واحد أو أكثر، مثل نوع الوسائط غير مدعوم. لمزيد من المعلومات، راجع القيمة نوصي بفحص أي ملفات وسائط تسبب أخطاءً وتأكيد أنها مدعومة بالفعل. على سبيل المثال، في UNIX يمكنك استخدام فحص الملف عبر سطر الأوامر لتحديد نوع MIME:
يمكنك حينها تأكيد ما إذا كان نوع MIME مدعومًا. راجع أنوع الوسائط المدعومة. |
طلب غير صالح |
الحساب في وضع الصيانة | حساب الأعمال في وضع الصيانة | حساب واتساب للأعمال في وضع الصيانة. أحد أسباب ذلك قد يكون أن الحساب يخضع إلى ترقية معدل الإرسال. |
طلب غير صالح |
عدد معلمات القالب غير متطابق | لا يتطابق عدد قيم المعلمات المتغيرة المضمنة في الطلب مع عدد معلمات المتغيرة المحددة في القالب. | راجع إرشادات قالب الرسالة وتأكد من أن الطلب يتضمن كل قيم المعلمات المتغيرة التي تم تحديدها في القالب. |
طلب غير صالح |
القالب غير موجود | القالب غير موجود باللغة المحددة أو أنه لم تتم الموافقة على القالب. | تأكد من الموافقة على القالب لديك وأن اسم القالب والإعداد المحلي للغة صحيحان. يُرجى الحرص على اتباع إرشادات قالب الرسالة. |
غير موجود |
يتجاوز طول نص القالب المُحدث الحد الأقصى | يتجاوز طول النص المُترجم الحد الأقصى. | تحقق من مدير واتساب للتأكد من ترجمة القالب. راجع تقييم الجودة وحالة القالب. |
طلب غير صالح |
تم انتهاك سياسة تنسيق الأحرف في القالب | ينتهك محتوى القالب سياسة واتساب. | راجع أسباب الرفض لتحديد الأسباب المحتملة للانتهاك. |
طلب غير صالح |
تنسيق معلمة القالب غير متطابق | تم تنسيق قيم المعلمات المتغيرة بشكل غير صحيح. | لا تستخدم قيم المعلمات المتغيرة المضمنة في الطلب التنسيق المحدد في القالب. راجع إرشادات قالب الرسالة. |
طلب غير صالح |
القالب موقوف مؤقتًا | القالب موقوف مؤقتًا نتيجة الجودة المنخفضة لذلك لا يمكن إرساله في رسالة قالب. | قم بتعديل القالب لتحسين الجودة وحاول مرة أخرى بمجرد الموافقة عليه. |
طلب غير صالح |
القالب معطَّل | تم إيقاف القالب مؤقتًا مرات عديدة نتيجة الجودة المنخفضة وأصبح الآن معطلاً بشكل دائم. | أنشئ قالبًا جديدًا يتضمن محتوى مختلفًا. |
طلب غير صالح |
الدفق محظور | الدفق في حالة محظورة. | تصحيح الدفق |
طلب غير صالح |
الدفق مقيد | الدفق ف حالة مقيدة وتم إرسال 10 رسائل بالفعل تستخدم هذا الدفق في الساعة الماضية. | تصحيح الدفق |
طلب غير صالح |
إلغاء التسجيل غير المكتمل | فشلت محاولة سابقة لإلغاء التسجيل. | يمكنك إلغاء تسجيل الرقم مرة أخرى قبل التسجيل. |
خطأ داخلي بالخادم |
الخادم غير متوفر مؤقتًا | الخادم غير متوفر مؤقتًا. | اطلع على صفحة حالة منصة واتساب للأعمال للتعرف على معلومات حالة API وتحقق من القيمة |
الخدمة غير متوفرة |
رقم التعريف الشخصي لعملية التحقق بخطوتين غير متطابق | رقم التعريف الشخصي لعملية التحقق بخطوتين غير صحيح. | تحقق من أن رقم التعريف الشخصي لعملية التحقق بخطوتين المضمن في الطلب صحيح. لإعادة تعيين رقم التعريف الشخصي لعملية التحقق بخطوتين:
|
طلب غير صالح |
تتعين إعادة التحقق من رقم الهاتف | يجب إعادة التحقق من رقم الهاتف قبل التسجيل. | تحقق من رقم الهاتف قبل تسجيله. |
طلب غير صالح |
تم إدخال تخمينات كثيرة للغاية لرقم التعريف الشخصي في عملية التحقق بخطوتين | عدد عمليات تخمين رقم التعريف الشخصي في عملية التحقق بخطوتين لرقم الهاتف هذا كبير للغاية. | حاول مرة أخرى بعد الفترة الزمنية المحددة في قيمة الاستجابة |
طلب غير صالح |
تم تخمين رقم التعريف الشخصي لعملية التحقق بخطوتين بشكل سريع جدًا | تم إدخال رقم التعريف الشخصي لعملية التحقق بخطوتين بسرعة كبيرة. | تحقق من قيمة الاستجابة |
طلب غير صالح |
رقم الهاتف غير مسجل | رقم الهاتف غير مسجل في منصة واتساب للأعمال. | يمكنك تسجيل رقم الهاتف قبل إعادة المحاولة. |
طلب غير صالح |
يُرجى الانتظار بضع دقائق قبل محاولة تسجيل رقم الهاتف هذا | تم حذف رقم الهاتف الذي كنت تحاول تسجيله مؤخرًا، ولم تكتمل عملية الحذف بعد. | يُرجى الانتظار 5 دقائق قبل إعادة محاولة الطلب. |
طلب غير صالح |
خطأ مستخدم عام | فشل إرسال الرسالة نتيجة وجود خطأ غير معروف في معلمات الطلب. | راجع مرجع نقطة النهاية لتحديد ما إذا كنت تستعلم عن نقطة النهاية باستخدام البنية الصحيحة. اتصل بفريق دعم الزبائن إذا استمر ظهور رمز الخطأ هذا في الاستجابة. |
طلب غير صالح |