التوثيق / مرجع الواجهة البرمجية

الأخطاء والحدود

رموز الحالة ورموز الأخطاء وحدود المعدل وكيفية معالجة كل منها.

تعيد الأخطاء جسم JSON فيه statusCode وcode ثابت وmessage مقروء. تفرّع حسب code لا حسب نص الرسالة.

Error
{ "statusCode": 409, "code": "window_closed", "message": "The 24-hour window is closed: the customer must message you first" }
HTTPcodeالمعنى والحل
401invalid_api_keyمفتاح مفقود أو غير صالح أو ملغى. افحص الترويسة.
403missing_scopeالمفتاح بلا الصلاحية. أنشئ مفتاحاً بها.
403plan_featureباقتك لا تشمل الواجهة البرمجية. رقِّ.
400invalid_phoneالمستلم ليس رقماً دولياً صالحاً.
400no_phone_numberلا رقم واتساب نشط أو from غير معروف.
409window_closedالنص الحر يتطلب أن يكون العميل قد كتب خلال 24 ساعة. أرسل قالباً.
403recipient_blocked, recipient_opted_outالمستلم محظور أو ألغى الاشتراك. لا تعد المحاولة.
403not_opted_inلا موافقة مسجلة. سجّلها عبر /contacts أو انتظر كتابة العميل.
404 / 409template_not_found, template_not_approvedالقالب غير موجود أو لم يُعتمد بعد.
400template_paramsعدد القيم يختلف عن القالب.
403subscription_inactiveالاشتراك غير نشط.
429quota_exceededبلغت حد الرسائل الشهري للباقة.
502send_failedرفضت واتساب الرسالة. راجع نص الخطأ.

#الحدود

  • حد المعدل: 120 طلباً في الدقيقة لكل عنوان. عند تجاوزه تتلقى 429؛ انتظر وأعد المحاولة.
  • الحصة: تُحتسب رسائل الـ API من رسائل باقتك الشهرية.
  • إعادة المحاولة: أعد فقط 429 و5xx مع تأخير متزايد، وبـ Idempotency-Key نفسه دائماً.
الأخطاء والحدود · توثيق رد