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