الأخطاء

كل خطأ من الواجهة البرمجية العامة لمجيب يستخدم نفس الظرف. تفرّع على 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	422
idempotency_error	409 / 422
rate_limit_error	429
quota_error	402
not_found_error	404
upstream_error	503
internal_error	500

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

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

code	HTTP	المعنى
invalid_api_key	401	مفتاح مفقود، مشوّه، غير معروف، أو ملغى. صحّح رأس Authorization.
revoked_api_key	401	المفتاح أُلغي من لوحة التحكم. أنشئ واحداً جديداً.
expired_api_key	401	المفتاح تجاوز تاريخ انتهائه. أنشئ واحداً جديداً.
insufficient_scope	403	المفتاح يفتقر للنطاق المطلوب (الاستجابة تحوي required_scope).
agent_not_authorized	403	المفتاح مقيّد بوكلاء معيّنين وهذا ليس منهم.
invalid_agent_id	422	agent_id ليس UUID صالحاً.
invalid_phone_number	422	to ليس رقم E.164 صالحاً.
invalid_from_phone	422	from ليس رقم E.164 صالحاً.
from_phone_not_found_for_agent	422	from مكوَّن جيداً لكن لا يطابق أي اتصال واتساب نشط على الوكيل (الاستجابة تحوي available_phones).
invalid_template_name	422	template.name مفقود أو فارغ.
invalid_request_body	422	حقل مطلوب مفقود أو من النوع الخاطئ (الاستجابة تحوي param تُسمي الحقل المخطئ).
idempotency_key_in_progress	409	نفس المفتاح + الجسم لا يزال يُعالَج. أعد المحاولة بعد Retry-After.
idempotency_key_in_use_with_different_params	422	نفس المفتاح استُخدم سابقاً بجسم مختلف (الاستجابة تحوي original_correlation_id).
rate_limit_exceeded	429	حد المعدّل لكل مفتاح تم بلوغه. تراجع وأعد بعد Retry-After.
message_limit_exceeded	402	(مستقبلي) حد رسائل الاشتراك تم بلوغه.
message_not_found	404	GET /v1/whatsapp/messages/{id} — المعرّف غير موجود أو ينتمي لمنظمة أخرى.
endpoint_not_found	404	المسار لا يُطابق أي نقطة /v1/. تحقّق من الأخطاء الإملائية.
whatsapp_unavailable	503	واجهة WhatsApp Cloud من ميتا غير متاحة. أعد بتراجع متصاعد.
internal_server_error	500	مشكلتنا. أعد بتراجع متصاعد؛ إن استمرّت، أرسل لنا correlation_id.

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

الحالة	المعنى
200	نجاح متزامن (مثل استعلام الحالة)
201	مورد أُنشئ
202	مقبول للمعالجة غير المتزامنة (مثل رسالة في طابور الإرسال)
400	طلب مشوَّه (JSON غير صالح)
401	فشل التوثيق
402	(مستقبلي) تجاوز الحصة
403	فشل الصلاحيات (نطاق، قائمة الوكلاء)
404	مورد غير موجود
409	تعارض (مفتاح إعادة قيد التنفيذ)
422	خطأ تحقق
429	تجاوز حد المعدّل
500	خطأ داخلي
503	منصة في المصب غير متاحة

كيف أستخدم 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 الخاصة بك دون استعلام آخر لاكتشاف ما هو صالح.