الأخطاء
كل خطأ تُرجعه الواجهة، مع رمزه الثابت وطريقة إصلاحه. اعتمد في منطقك على code، وراجع شكل الأخطاء.
| HTTP | الرمز | طريقة الإصلاح |
|---|---|---|
| 401 | api_key_missingلا يوجد مفتاح API | أرسل مفتاحك في الترويسة Authorization: Bearer sk_live_… (أو sk_test_…). |
| 401 | api_key_invalidمفتاح API غير صالح | انسخ المفتاح مرة أخرى من المطورين ← مفاتيح API. تبدأ المفاتيح بـ sk_live_ أو sk_test_. |
| 401 | api_key_revokedالمفتاح ملغى | ألغى أحدهم هذا المفتاح. أنشئ مفتاحًا جديدًا من المطورين ← مفاتيح API. |
| 401 | api_key_expiredانتهت صلاحية المفتاح | تجاوز المفتاح تاريخ انتهائه. أنشئ مفتاحًا جديدًا. |
| 402 | subscription_inactiveالاشتراك غير نشط | جدّد اشتراك مساحة العمل من الفوترة. تبقى عمليات القراءة متاحة خلال ذلك. |
| 402 | quota_exceededنفد الرصيد المتاح | استُهلك رصيد الباقة لهذه الفترة. قم بالترقية أو أضف إضافة من الفوترة. يوضّح entitlement الرصيد المقصود. |
| 403 | insufficient_scopeصلاحية ناقصة | المفتاح لا يملك الصلاحية الموجودة في required_scope. أنشئ مفتاحًا يملكها. |
| 403 | api_access_not_in_planالواجهة غير مشمولة في الباقة | يتطلب الوصول الحي للواجهة باقة تشمله. مفاتيح الاختبار تعمل في كل الباقات. |
| 403 | workspace_suspendedمساحة العمل موقوفة | تواصل مع الدعم لإعادة تفعيل مساحة العمل. |
| 403 | capability_disabledالميزة موقوفة | هذه الميزة موقوفة لمساحة العمل. تواصل مع الدعم. |
| 403 | test_mode_unsupportedغير متاح في وضع الاختبار | هذا الطلب يعمل على بيانات عملاء حقيقية ولا توجد له نسخة محاكاة. استخدم مفتاح تشغيل، أو مساحة عمل منفصلة للتجربة. |
| 400 | invalid_jsonJSON غير صالح | جسم الطلب ليس JSON صالحًا. راجع علامات الاقتباس والفواصل، وأرسل Content-Type: application/json. |
| 422 | parameter_missingحقل مفقود | يسمّي param الحقل المفقود، ويسرد details كل الحقول. |
| 422 | parameter_invalidحقل غير صالح | يسمّي param الحقل، ويوضح message ما الخطأ فيه. |
| 404 | resource_missingغير موجود | لا يوجد عنصر بهذا المعرّف في مساحة العمل. معرّفات الاختبار (msg_test_…) تُقرأ بمفتاح اختبار فقط، والمعرّفات الحية بمفتاح تشغيل فقط. |
| 404 | route_not_foundرابط غير معروف | راجع المسار والطريقة في مرجع الواجهة. كل المسارات تبدأ بـ /v1/. |
| 405 | method_not_allowedطريقة HTTP خاطئة | الرابط موجود لكن ليس بهذه الطريقة. راجع مرجع الواجهة. |
| 413 | payload_too_largeالطلب كبير جدًا | أرسل جسم طلب أصغر. |
| 422 | idempotency_key_reusedتكرار Idempotency-Key | المفتاح خاص بطلب واحد. استخدم Idempotency-Key جديدًا لجسم مختلف. |
| 409 | idempotency_in_progressالطلب نفسه ما زال قيد التنفيذ | الطلب الأول بهذا المفتاح لم ينتهِ بعد. أعد المحاولة بعد ثانية. |
| 422 | window_closedنافذة الـ24 ساعة مغلقة | لا يسلّم واتساب الرسائل الحرة إلا خلال 24 ساعة من آخر رسالة للعميل. أرسل قالبًا معتمدًا بدلًا منها، وتُفتح المحادثة من جديد عندما يرد العميل. |
| 422 | template_not_foundالقالب غير موجود | راجع اسم القالب ولغته، أو استخدم معرّفه tpl_…. |
| 422 | template_not_approvedالقالب غير معتمد | لا يُرسل إلا ما اعتمده واتساب من قوالب. انتظر اعتماده، أو أصلح سبب الرفض من صفحة القوالب. |
| 422 | template_variables_mismatchمتغيرات القالب غير مطابقة | أرسل قيمة واحدة غير فارغة لكل {{n}} في template.variables.body وبالترتيب. |
| 409 | recipient_not_consentedالمستلِم لم يوافق | جهة الاتصال لم توافق على رسائل الأعمال. إن كانت موافقتها لديك في مكان آخر، أعد الإرسال مع "consent_confirmed": true (تُسجَّل الموافقة). |
| 422 | recipient_opted_outالمستلِم ألغى الاشتراك | طلبت جهة الاتصال عدم مراسلتها. لا تُعد المحاولة. |
| 422 | sender_not_configuredلا يوجد رقم مُرسِل | اربط رقم واتساب من الإعدادات ← القنوات، أو مرّر from صحيحًا. |
| 422 | sender_not_sendableالرقم لا يستطيع الإرسال | يوضّح reason السبب (مثل انقطاع الربط أو انتهاء الرمز). أصلح الرقم من الإعدادات ← القنوات. |
| 422 | channel_errorرفض واتساب الرسالة | يحمل channel_error رمز واتساب ورسالته. ابحث عن الرمز في قائمة أخطاء واتساب. |
| 409 | send_outcome_unknownربما أُرسلت المحاولة السابقة | تلقى طلب سابق بنفس Idempotency-Key ردًّا غير واضح من واتساب. تحقق عبر GET /v1/messages?reference=… قبل الإرسال مرة أخرى. |
| 422 | channel_not_connectedالقناة غير متصلة | اربط القناة (أو أعد ربطها) من الإعدادات ← القنوات. يوضّح param الحقل الذي حدّد القناة. |
| 409 | resource_existsموجود مسبقًا | يوجد عنصر آخر يستخدم هذه القيمة الفريدة (رقم هاتف أو بريد أو اسم). يوضّح existing_id العنصر الموجود متى أمكن: حدّثه بدلًا من ذلك، أو استخدم نقطة upsert. |
| 409 | resource_in_useما زال مستخدمًا | ما زال شيء يعتمد على هذا العنصر (حملة جارية تستخدم القالب، أو رسالة تستخدم الملف). يوضّح details ما هو. أنهِ ذلك أو احذفه أولًا. |
| 409 | state_conflictغير مسموح في الحالة الحالية | الإجراء لا يناسب حالة العنصر الحالية، مثل إغلاق محادثة مغلقة أصلًا أو بدء حملة بدأت. اقرأ العنصر وتحقق من state أو status ثم قرّر. |
| 422 | assignee_invalidلا يمكن إسناد المحادثة لهذا العضو | أسند المحادثة لعضو من GET /v1/members يستطيع رؤية قناتها. يُرفض المشاهدون والأعضاء الذين لا يملكون صلاحية على ذلك الرقم. |
| 422 | media_invalidالملف غير مقبول | يضع واتساب حدودًا لكل نوع وسائط: الصور JPEG/PNG حتى 5 ميجابايت، الفيديو MP4/3GPP حتى 16 ميجابايت، الصوت حتى 16 ميجابايت، المستندات حتى 100 ميجابايت، الملصقات WebP حتى 100 كيلوبايت (500 للمتحركة). يوضّح message القاعدة التي لم تتحقق. |
| 422 | flow_not_triggerableلا يمكن تشغيل التدفق | لا يمكن تشغيل تدفق عبر الواجهة إلا إذا كان منشورًا ومشغّله "API / ويب هوك". انشره أو غيّر مشغّله من منشئ التدفقات. |
| 422 | webhook_url_invalidرابط الويب هوك غير مقبول | استخدم رابط https:// عامًا. العناوين الخاصة والمحلية وعناوين بيانات السحابة مرفوضة. |
| 422 | webhook_endpoint_limitنقاط استقبال كثيرة | احذف نقطة لم تعد تستخدمها (10 لكل مساحة عمل). |
| 429 | rate_limitedطلبات كثيرة | انتظر عدد ثواني Retry-After. نظّم طلباتك بالاعتماد على ترويسات RateLimit-* في كل استجابة. |
| 500 | internal_errorخطأ في الخادم | أعد المحاولة بنفس Idempotency-Key. إن استمر الخطأ تواصل مع الدعم واذكر request_id. |
| 503 | platform_pausedالإرسال متوقف مؤقتًا | الإرسال متوقف على مستوى المنصة لصيانة أو حادث. أعد المحاولة لاحقًا. |
| 503 | service_unavailableغير متاح مؤقتًا | أعد المحاولة مع زيادة فترة الانتظار تدريجيًا. |