الأخطاء

كل خطأ من الواجهة البرمجية العامة لمجيب يستخدم نفس الظرف. تفرّع على code (ثابت، إضافي إلى الأبد) — لا تفرّع أبداً على message (مقروء بشرياً، قد يُعاد صياغته دون إشعار).

كيف تبدو استجابة الخطأ؟

{
  "error": {
    "type":           "validation_error",
    "code":           "invalid_from_phone",
    "message":        "The 'from' field must be an E.164 phone number...",
    "param":          "from",
    "correlation_id": "req_01KQ..."
  }
}

الحقل	حاضر دائماً؟	الغرض
type	نعم	تصنيف ثابت لكتل catch
code	نعم	سبب محدّد ثابت — تفرّع على هذا
message	نعم	مقروء بشرياً؛ لا تستخدم كمفتاح أبداً
correlation_id	نعم	معرّف تتبّع لسجلاتنا — اقتبس في تذاكر الدعم
حقول إضافية	أحياناً	سياق لكل خطأ (مثل param، available_phones، original_correlation_id)

ما أنواع الخطأ؟

مجموعة صغيرة وثابتة من التصنيفات. إضافية إلى الأبد — قد تظهر أنواع جديدة، لن يُحذَف أي قائم:

type	HTTP المعتاد
authentication_error	401
permission_error	403
validation_error	413، 422
idempotency_error	409 / 422
rate_limit_error	429
quota_error	402
conflict_error	409
not_found_error	404
internal_error	500، 503 (و401 حين يتعذّر فحص المفتاح)

ما الكتالوج الكامل للرموز؟

الرموز enum ثابت. رموز جديدة تظهر دون إشعار؛ لا شيء قائم سيُعاد تسميته أو غرضه.

code	HTTP	المعنى
invalid_api_key	401	مفتاح مفقود، مشوّه، غير معروف، ملغى، أو منتهي الصلاحية. صحّح رأس Authorization.
insufficient_scope	403	المفتاح يفتقر للنطاق المطلوب (الاستجابة تحوي required_scope).
agent_not_authorized	403	المفتاح مقيّد بوكلاء معيّنين وهذا ليس منهم.
shared_with_other_agents	403	قاعدة المعرفة، أو تسجيل دخول موقع أداة ربط نظامك، يستخدمها أيضاً وكلاء لا يستطيع المفتاح العمل عليهم، فلا يستطيع تغييرها.
feature_not_available	403	باقتك لا تشمل هذا: أدوات ربط نظامك متاحة في الباقات المدفوعة. قم بالترقية، أو استخدم نقاط النهاية التي تشملها باقتك.
not_note_author	403	لا يعدّل الملاحظة أو يحذفها إلا كاتبها؛ والمفتاح يعمل باسم الشخص الذي أنشأه.
system_note_read_only	403	الملاحظات التي يسجّلها مجيب، مثل تغييرات حالة العميل المحتمل، لا تُعدَّل ولا تُحذف.
agent_id_required	403	مفتاح مقيّد ببعض الوكلاء استدعى نقطة واتساب دون agent_id صالح.
agent_not_found	404	الوكيل ليس من وكلاء منظمتك.
not_found	404	المحادثة أو جهة الاتصال أو الملاحظة أو العميل المحتمل أو حقل العملاء المحتملين أو قاعدة المعرفة أو القناة أو أداة ربط نظامك أو التعليق لا تخص هذا الوكيل (والمحادثة المحذوفة غير موجودة كذلك)، أو رسالة المحادثة التي طلبتها ليست من رسائلها، أو القناة التي طلبت قوالبها ليست رقم واتساب. وفي سجل الاستخدام: لا يوجد اشتراك لمنظمتك.
message_not_found	404	GET /v1/whatsapp/messages/{id}: المعرّف غير موجود، أو ينتمي لمنظمة أخرى، أو أُرسلت الرسالة عبر وكيل خارج قائمة وكلاء المفتاح.
endpoint_not_found	404	لا تطابق أي نقطة /v1/ الطريقةَ والمسار، ومن ذلك معرّف ليس UUID. تحقّق من الأخطاء الإملائية.
lead_capture_not_found	404	لا يملك الوكيل أداة حفظ عميل، فلا توجد له تعليمات لحفظ العملاء تُقرأ أو تُغيَّر. تواصل مع دعم مجيب لإضافة الأداة.
invalid_request_body	422	حقل مفقود أو من النوع الخاطئ أو يتجاوز حداً أو يخالف الصيغة (مثل phone لعميل محتمل أو mobile لجهة اتصال ليس بصيغة E.164)، أو قيمة معامل استعلام غير صالحة (الاستجابة تحوي param تُسمّيه).
invalid_request	422	قاعدة عمل رفضت التغيير (مثل حالة عميل غير معروفة أو مفتاح محجوز لحقل عميل محتمل)، أو cursor ليس مما أعادته الواجهة، أو after في عرض الرسائل ليس رسالة من المحادثة أو أُرسل مع cursor (وكلاهما مع param: after). توضّح message السبب.
invalid_date_range	422	نافذة التحليلات خارج الحدود: to قبل from، أو تاريخ بعد اليوم بتوقيت UTC، أو نافذة أطول مما تسمح به نقطة النهاية. توضّح message السبب.
no_settings	422	تحديث إعدادات أو محادثة لم يرسل أي شيء لتغييره.
messaging_window_closed	422	رد في محادثة لم يكتب عميلها خلال آخر 24 ساعة: لن يوصله واتساب أو فيسبوك أو إنستجرام. لم يُرسَل شيء. وعلى واتساب أرسل قالباً.
channel_not_supported	422	رد في محادثة على قناة لا يستطيع مجيب الإرسال عليها بعد (TikTok). لم يُرسَل شيء.
comment_already_hidden	422	hideComment على تعليق مخفي أصلًا.
comment_not_hidden	422	unhideComment على تعليق غير مخفي.
platform_hide_failed	422	رفض فيسبوك أو إنستجرام إخفاء التعليق أو إظهاره، كأن يكون قد حُذف، أو تعذّر الوصول إليه. وقد يكون مؤقتًا.
field_not_writable	422	تحديث للوكيل أرسل قيمة لحقل لا يستطيع المفتاح تغييره: status (فلا يستطيع المفتاح حذف وكيل)، أو ai_model، أو model_provider، أو avatar_url، أو language (الاستجابة تحوي param تُسمّيه). لم يتغيّر شيء.
unknown_timezone	422	time_zone ليس معرّف منطقة زمنية من IANA بصيغة Region/City، مثل Africa/Cairo (والتوقيت العالمي المنسّق هو Etc/UTC).
invalid_follow_up_platform	422	قناة متابعة ليست whatsapp أو facebook أو instagram.
invalid_follow_up_steps	422	خطوات أكثر من المسموح، أو تأخير خارج النطاق المسموح، أو خطوتان بالتأخير نفسه.
assignee_not_allowed	422	عضو الفريق لا يستطيع فتح الوكيل (ليس من منظمتك، أو مقيّد بوكلاء آخرين)، فلا يمكن إسناد العميل أو المحادثة إليه. اختر شخصاً يظهر له can_open_agent: true في قائمة أعضاء الوكيل.
system_field	422	حقول العملاء المحتملين المدمجة (built_in: true)، ومنها حالات العملاء المحتملين، لا تُغيَّر ولا تُحذف عبر الواجهة.
lead_field_limit_reached	422	لدى الوكيل بالفعل أكبر عدد من حقول العملاء المحتملين المخصّصة تسمح الواجهة بإضافته. احذف أولاً حقلاً لم يعد يحتاجه.
connection_inactive	409	القناة مفصولة (active: false)، فلا يمكن تغيير إعداداتها ولا عرض قوالبها. أعد ربطها من لوحة التحكم أولاً.
connection_needs_reconnection	409	لم تعد ميتا تقبل صلاحية الوصول لرقم واتساب (أُلغيت أو انتهت، أو غادر الرقم حساب واتساب للأعمال الخاص به)، فلا يمكن قراءة قوالبه. أعد ربط الرقم من لوحة التحكم؛ إعادة المحاولة لن تفيد.
field_key_taken	409	لدى الوكيل بالفعل حقل عميل محتمل بهذا المفتاح، ومن ذلك الحقول المدمجة. لم يُنشأ شيء. والإنشاء المُعاد بعد ضياع الاستجابة ينتهي هنا أيضاً، فاعرض حقول العملاء المحتملين وتابع.
no_current_usage_period	409	لا تغطي أي فترة فوترة من اشتراكك الوقت الحالي، فيعامله مجيب على أنه غير مُجدَّد ولا يرد الذكاء الاصطناعي حتى تبدأ فترة. يزول حين يصل التجديد؛ وإن استمر، تواصل مع الدعم مع correlation_id. ويُعيده GET /v1/organization/usage أيضاً حين لا يكون لمنظمتك اشتراك أصلاً.
usage_periods_overlap	409	أكثر من فترة فوترة من اشتراكك تغطي الوقت الحالي، فلا يستطيع مجيب معرفة الحدود المطبّقة. تواصل مع الدعم مع correlation_id.
login_shared	409	تسجيل دخول ربط نظامك الذي أرسلته يختلف عن المحفوظ للموقع، أو يحمل سرّاً، وتستخدمه أدوات أخرى. أرسل change_shared_login: true لتغييره لها كلها، أو لا ترسل login.
tool_not_tested	409	لا تُشغَّل أداة ربط نظامك إلا بعد اختبار ناجح لطلبها الحالي. اختبرها ثم شغّلها.
request_body_too_large	413	جسم الطلب أكبر من 1 MB.
invalid_agent_id	422	agent_id ليس UUID صالحاً (نقاط واتساب).
invalid_phone_number	422	to ليس رقم E.164 صالحاً (نقاط واتساب). أما phone لعميل محتمل أو mobile لجهة اتصال بغير صيغة E.164 فيعيد invalid_request_body.
invalid_from_phone	422	from ليس رقم E.164 صالحاً.
from_phone_not_found_for_agent	422	from مكوَّن جيداً لكن لا يطابق أي اتصال واتساب نشط على الوكيل (الاستجابة تحوي available_phones).
template_header_media_url_invalid	422	template.header_media_url ليس رابط HTTPS كاملاً.
template_not_found	422	لا يوجد على الاتصال قالب بهذا الاسم، أياً كانت حالته (الاستجابة تحوي available_templates). وحين يتعذّر على مجيب قراءة القوالب من ميتا، أو يكون لدى الرقم قوالب أكثر مما يقرؤه مجيب ولا يكون هذا القالب بينها، يُتخطّى هذا الفحص ويُقبَل الإرسال.
template_not_found_for_language	422	لا توجد للقالب نسخة بهذه اللغة، أياً كانت حالتها (الاستجابة تحوي available_languages).
idempotency_key_in_progress	409	طلب بهذا المفتاح لا يزال قيد التنفيذ، أو طلب به رُفض أو فشل بعد أن حجز المفتاح (مثل messaging_window_closed في رد) وقد بدأ قبل أقل من 60 ثانية، أياً كان الجسم. أعد المحاولة بعد Retry-After، أو أرسل الطلب المصحَّح بمفتاح جديد.
idempotency_key_in_use_with_different_params	422	المفتاح يخص طلباً سابقاً مقبولاً يختلف عن هذا الطلب: بجسم آخر، أو على نقطة نهاية أو محادثة أخرى (فالنص نفسه ردّاً في محادثة أخرى يُعدّ طلباً مختلفاً). الاستجابة تحوي original_correlation_id.
idempotency_unknown_outcome	500	خلل داخلي في فحص الإعادة الآمنة (غير متوقَّع). أعد المحاولة بالمفتاح والجسم نفسيهما.
unknown_send_outcome	500	خلل داخلي في قراءة نتيجة الإرسال (غير متوقَّع). استعلم عن الرسالة قبل الإرسال مرة أخرى.
rate_limit_exceeded	429	تم بلوغ حد المعدّل لكل مفتاح: الحد الافتراضي، أو الحد الأقل الخاص بعرض قوالب واتساب أو بالردود في المحادثات. تراجع وأعد بعد Retry-After.
test_rate_limited	429	شغّلت شركتك اختبارات كثيرة لأدوات ربط نظامك في هذه الدقيقة (30، عبر مفاتيحها ولوحة التحكم). أعد المحاولة بعد Retry-After.
message_limit_exceeded	402	محجوز: حد رسائل الاشتراك. لا يُرسَل اليوم.
access_unavailable	503	تعذّر إجراء فحص الصلاحيات: صلاحيات المفتاح، أو صلاحيات عضو الفريق عند إسناد عميل محتمل أو محادثة. أعد المحاولة بتراجع متصاعد.
meta_unavailable	503	لم تُعِد ميتا ما طُلب منها، مثل قوالب رقم واتساب (انقطاع، أو انتهاء المهلة، أو حد المعدّل لدى ميتا نفسها). أعد المحاولة بتراجع متصاعد.
internal_server_error	500، 401	مشكلتنا: أعد بتراجع متصاعد، وإن استمرّت أرسل لنا correlation_id. ومع 401 يعني أننا لم نتمكّن من فحص المفتاح؛ أعد المحاولة ولا تُدوّره.

ما حالات HTTP التي قد تُعيدها الواجهة؟

الحالة	المعنى
200	نجاح مع جسم (قراءة أو تحديث أو إسناد)
201	مورد أُنشئ (عميل محتمل، ملاحظة، قاعدة معرفة، حقل عميل محتمل، أداة ربط نظامك، رد في محادثة)
202	مقبول للمعالجة غير المتزامنة (رسالة في طابور الإرسال)
204	نجاح دون جسم (حذف)
401	فشل التوثيق
402	محجوز: تجاوز الحصة
403	فشل الصلاحيات (نطاق، قائمة الوكلاء، معرفة أو تسجيل دخول مشترك، كاتب الملاحظة، ميزة لا تشملها باقتك)
404	مورد غير موجود
409	تعارض (مفتاح إعادة قيد التنفيذ، أو قناة مفصولة أو تحتاج إعادة ربط، أو مفتاح حقل عميل محتمل موجود بالفعل، أو عدم وجود فترة فوترة حالية واحدة، أو تسجيل دخول ربط نظامك مشترك، أو أداة لم تُختبر)
413	جسم الطلب أكبر من 1 MB
415	الجسم لم يُرسَل بصيغة application/json (جسم problem-details قياسي، لا الظرف)
422	خطأ تحقق، ومنه جسم ليس JSON صالحاً
429	تجاوز حد المعدّل
500	خطأ داخلي
503	فحص الصلاحيات أو ميتا غير متاح مؤقتاً

أي الأخطاء أعيد المحاولة معها؟

أعد المحاولة مع المؤقّتة منها فقط. انتظر Retry-After مع 429 ومع 409 idempotency_key_in_progress. واستخدم التراجع المتصاعد مع أخطاء 503، ومع أخطاء 500 عدا unknown_send_outcome، ومع 422 platform_hide_failed (فقد يكون فيسبوك أو إنستجرام غير متاح فحسب)، ومع 401 رمزه internal_server_error. أما بقية الأخطاء فتحتاج تغييراً قبل أن ترسل الطلب مرة أخرى.

الخطأ	ماذا تفعل
409 connection_inactive، 409 connection_needs_reconnection	أعد ربط القناة من لوحة التحكم، ثم حاول مرة أخرى.
409 field_key_taken	الحقل موجود بالفعل: اعرض حقول العملاء المحتملين للوكيل وتابع.
409 no_current_usage_period	انتظر: يزول حين يصل التجديد. تواصل مع الدعم إن استمر. وإن لم يكن لديك اشتراك أصلاً فلن يزول حتى تشترك.
409 usage_periods_overlap	تواصل مع الدعم مع correlation_id.
409 login_shared	لا ترسل login، أو أرسل change_shared_login: true إن كان يجب أن يتغيّر لكل أدوات الموقع.
409 tool_not_tested	اختبر الأداة، ثم شغّلها في طلب مستقل.
500 unknown_send_outcome	استعلم عن الرسالة قبل إرسالها مرة أخرى.
422 messaging_window_closed	انتظر أن يكتب العميل، أو أرسل قالباً على واتساب.
422 platform_hide_failed	أعد المحاولة لاحقاً مع التراجع المتصاعد. وإن استمر الفشل فالأرجح أن التعليق حُذف.
422 comment_already_hidden، 422 comment_not_hidden	لا شيء لتصحيحه: التعليق على الحال التي طلبتها. وبعد 500 يعني ذلك أن طلبك الأول نجح.
أي 4xx آخر	صحّح الطلب؛ يوضّح code وmessage ما يجب تغييره.

كيف أستخدم correlation_id؟

احفظه عند كل خطأ. عند تواصلك مع الدعم، الصق correlation_id من الاستجابة الفاشلة — يمكننا تتبّع دورة حياة الطلب الكاملة في سجلاتنا في ثوانٍ.

يمكنك أيضاً إرسال معرّف تتبّع خاص بك وسنحترمه إن كان صالحاً:

curl ... -H "X-Correlation-ID: my-app-trace-abc123"

حتى 128 حرفاً: حروف وأرقام و_ و-. المعرّف الذي يخالف هذه القواعد يُتجاهَل دون أي خطأ ونُولّد بدلاً منه معرّفاً جديداً، لذا خذ المعرّف من رأس الاستجابة ولا تفترض أن معرّفك قد حُفظ. نُعيد المعرّف في رأس الاستجابة X-Correlation-ID ونُضمِّنه في أي ظرف خطأ. إن لم ترسل واحداً، نُولّد req_<26-char ULID>.

أسئلة شائعة

لماذا يُغطي invalid_api_key كل هذه الحالات الفرعية؟

رمز واحد يُبسّط منطق العميل — يحتاج كودك فرعاً واحداً فقط لـ"فشل التوثيق". حقل message يُميّز للبشر أثناء التصحيح، لكن لا ينبغي أن تتفرّع على النص. عامل أي invalid_api_key كـ"صحّح المفتاح وأعد".

هل ستضيف رموز خطأ جديدة لاحقاً؟

نعم. قد تظهر قيم code جديدة دون إشعار مع إضافة الميزات. اجعل عبارات switch/match افتراضياً آمنة — تراجع إلى "خطأ غير معروف، سجّل وأظهر للمستخدم".

ماذا عن أخطاء على مستوى الحقول مع حقول غير صالحة متعدّدة؟

حالياً، تُعيد الواجهة أول خطأ تحقق تواجهه. قد نُضيف شكلاً أغنى متعدّد الأخطاء لاحقاً كتغيير إضافي (حقل اختياري جديد على الظرف، لا يستبدل الحقول القائمة). الآن، صحّح خطأ واحداً في كل مرة.

ما original_correlation_id؟

يُعاد على idempotency_key_in_use_with_different_params. يُشير إلى معرّف التتبّع للطلب الذي حجز مفتاح الإعادة أصلاً، حتى تجد ذلك الطلب السابق في سجلات تطبيقك.

ما available_phones؟

يُعاد على from_phone_not_found_for_agent. يُدرج كل رقم واتساب نشط على الوكيل بصيغة E.164، حتى تُصحّح قيمة from الخاصة بك دون استعلام آخر لاكتشاف ما هو صالح.