أخطاء API v2

يأتي كل خطأ في API v2 مع رمز حالة HTTP حقيقي وبنية JSON نفسها. تعرض هذه الصفحة كل code، ومعناه، وما يجب فعله. وكل استجابة خطأ تحتوي في docs على رابط إلى رمزها هنا.

كائن الخطأ#

{
  "error": {
    "code": "not_cancellable",
    "message": "Only a waiting message can be cancelled.",
    "field": null,
    "docs": "https://wbiztool.com/docs/api/v2/errors/#not_cancellable",
    "request_id": "req_4f1c2a9b8e7d6c5b4a392817",
    "status": "sent"
  }
}

تضيف بعض الرموز تفاصيل خاصة بها، مثل status أو count أو used أو limit؛ وهي مذكورة مع الرمز. تحمل الاستجابة ذات حالة HTTP ‏401 أيضًا ترويسة WWW-Authenticate: Bearer realm="wbiztool"، وتحمل الاستجابات ذات الحالة 429 (والحالة 409 الخاصة بـ idempotency_in_progress) ترويسة Retry-After.

باختصار: تعني 4xx أن الطلب يحتاج إلى تغيير (أو إلى الانتظار في حالتي 409 و429)؛ وإعادة إرساله دون تغيير تعطي الاستجابة نفسها. وتعني 5xx أن المشكلة من جهتنا؛ أعد المحاولة لاحقًا مع Idempotency-Key نفسه.

المصادقة والحدود#

api_v2_not_enabled#

‏HTTP 403. ‏API v2 غير متاح لمساحة العمل هذه. إذا ظهر لك هذا الخطأ، فتواصل معنا.

ما يجب فعله: واصل استخدام API v1 في الوقت الحالي. تُظهر بطاقة مفاتيح API v2 في الإعدادات ← مفاتيح API متى يصبح متاحًا لك.

missing_api_key#

‏HTTP 401. لا يحتوي الطلب على ترويسة Authorization: Bearer …، أو أنها فارغة أو تستخدم مخططًا آخر.

ما يجب فعله: أرسل Authorization: Bearer wbz_live_… (أو wbz_test_…) مع كل طلب. راجع المفاتيح.

invalid_api_key#

‏HTTP 401. المفتاح ليس مفتاح WbizTool v2: مكتوب خطأً، أو مقطوع، أو ليس مفتاحًا أنشأناه.

ما يجب فعله: انسخ المفتاح مرة أخرى، دون مسافات أو علامات اقتباس. لا يمكن عرض المفتاح مرة أخرى بعد إنشائه؛ فإذا فقدته، فأنشئ مفتاحًا جديدًا في الإعدادات ← مفاتيح API.

v1_key_on_v2#

‏HTTP 401. المفتاح هو مفتاح API v1 ‏(40 حرفًا، من الأرقام ومن a إلى f). لا تعمل مفاتيح v1 إلا على /api/v1/.

ما يجب فعله: أنشئ مفتاح v2 في بطاقة مفاتيح API v2 في الإعدادات ← مفاتيح API، أو استدعِ API v1.

api_key_revoked#

‏HTTP 401. أُبطل المفتاح في الإعدادات ← مفاتيح API، أو حُذفت مساحة عمله أو عُطّلت.

ما يجب فعله: استخدم مفتاحًا آخر، أو اطلب من مالك مساحة العمل أن ينشئ مفتاحًا جديدًا.

api_key_expired#

‏HTTP 401. انقضى تاريخ انتهاء صلاحية المفتاح.

ما يجب فعله: اطلب من مالك مساحة العمل أن ينشئ مفتاحًا جديدًا، واستبدل به المفتاح القديم في تطبيقك.

too_many_auth_failures#

‏HTTP 429. أكثر من 30 طلبًا خلال دقيقة واحدة من عنوان IP الخاص بك حملت مفتاحًا خاطئًا. قيمة Retry-After هي 60.

ما يجب فعله: توقّف وأصلح المفتاح في تطبيقك، ثم حاول مرة أخرى بعد دقيقة.

demo_account#

‏HTTP 403. لا يمكن لمساحة العمل التجريبية (Demo) استخدام API.

ما يجب فعله: سجّل للحصول على حسابك الخاص وأنشئ مفتاحًا فيه.

missing_scope#

‏HTTP 403. لا يملك المفتاح النطاق (scope) الذي يحتاج إليه هذا الطلب. يذكر required_scope في الخطأ النطاق المطلوب، مثل messages:send.

ما يجب فعله: أنشئ مفتاحًا بهذا النطاق (لا يمكن إضافة نطاقات إلى مفتاح موجود). راجع النطاقات.

rate_limited#

‏HTTP 429. أرسل المفتاح أكثر من 60 طلبًا في هذه الدقيقة، أو أكثر من 10,000 طلب اليوم (بتوقيت UTC).

ما يجب فعله: انتظر عدد الثواني المذكور في Retry-After، ثم حاول مرة أخرى. وزّع الطلبات على فترات، واستخدم POST /messages/batch للمستلمين الكثيرين، وwebhooks بدلًا من الاستطلاع المتكرر. راجع حدود المعدل.

الطلب#

not_found#

‏HTTP 404. لا يوجد شيء على هذا العنوان: المسار مكتوب خطأً، أو ليس مسارًا من مسارات API v2.

ما يجب فعله: قارن المسار بالمرجع، مثل /api/v2/messages وليس /api/v2/message.

invalid_json#

‏HTTP 400. الجسم ليس JSON صالحًا، وغالبًا بسبب فاصلة زائدة في النهاية أو فاصل أسطر غير مُهرَّب في text.

ما يجب فعله: راجع JSON، واكتب الأسطر الجديدة داخل النصوص على شكل \n. دع مكتبة HTTP لديك تبني الجسم (json= في Python requests، وJSON.stringify في JavaScript).

unsupported_content_type#

‏HTTP 415. لم يُرسَل الجسم بالطريقة التي تقبلها نقطة النهاية هذه: كل نقاط النهاية تقبل application/json، باستثناء POST /media التي تقبل multipart/form-data.

ما يجب فعله: اضبط Content-Type: application/json وأرسل JSON، أو أرسل الرفع بصيغة multipart مع الحقل file.

method_not_allowed#

‏HTTP 405. المسار موجود ولكن ليس بهذه الطريقة (method)، مثل PUT /messages/9817263.

ما يجب فعله: استخدم الطريقة التي يعرضها المرجع. تعديل تذكير يكون بـ PATCH، وإلغاء رسالة يكون بـ DELETE.

request_too_large#

‏HTTP 413. جسم الطلب كبير جدًا.

ما يجب فعله: أرسل كمية أقل في الطلب الواحد، فمثلًا قسّم القائمة الطويلة إلى عدة دفعات.

validation_failed#

‏HTTP 400. بنية الطلب غير صحيحة: حقل مطلوب مفقود، أو قيمة من نوع خاطئ أو طويلة جدًا، أو حقل غير معروف، أو limit ليست بين 1 و100. يذكر field أول مشكلة ويشرحها message؛ ويعرض errors أي مشكلات أخرى.

ما يجب فعله: أصلح الحقل المذكور في field. أسماء الحقول بصيغة snake_case والحقول غير المعروفة تُرفض، لذا تحقّق من الأخطاء الإملائية مثل txt أو phone_number.

invalid_cursor#

‏HTTP 400. قيمة cursor تالفة، أو أُنشئت لعوامل تصفية غير التي في هذا الطلب.

ما يجب فعله: أرسل next_cursor الذي حصلت عليه كما هو تمامًا، مع عوامل التصفية نفسها التي في الصفحة الأولى. لتغيير عوامل التصفية، ابدأ من جديد دون cursor.

invalid_idempotency_key#

‏HTTP 400. ترويسة Idempotency-Key فارغة، أو أطول من 255 حرفًا، أو تحتوي على أحرف غير قابلة للطباعة.

ما يجب فعله: استخدم UUID أو نصًا قصيرًا آخر من الحروف والأرقام والشرطات.

idempotency_key_reused#

‏HTTP 422. استُخدم Idempotency-Key هذا بالفعل خلال آخر 24 ساعة مع طلب مختلف: طريقة أو مسار أو جسم آخر.

ما يجب فعله: استخدم مفتاحًا جديدًا لكل طلب جديد، ولا تُعِد استخدام مفتاح إلا لإعادة محاولة الطلب نفسه تمامًا. راجع Idempotency-Key.

idempotency_in_progress#

‏HTTP 409. لا يزال الطلب الأول الذي يحمل Idempotency-Key هذا قيد المعالجة. قيمة Retry-After هي 1.

ما يجب فعله: انتظر ثانية وأرسل الطلب نفسه مرة أخرى: ستحصل على استجابة الطلب الأول.

internal_error#

‏HTTP 500. حدث خطأ ما من جهتنا. ونحن نُبلَّغ به.

ما يجب فعله: أعد المحاولة لاحقًا مع Idempotency-Key نفسه، حتى لا يُنفَّذ العمل مرتين. وإذا استمر حدوثه، فتواصل معنا مع ذكر request_id.

الرسائل#

text_required#

‏HTTP 400. لا تحتوي الرسالة على text ولا على media، أو أن النص مسافات فقط. وفي التذكير، يكون text مطلوبًا.

ما يجب فعله: أرسل text أو media أو كليهما.

text_too_long#

‏HTTP 400. ‏text أطول من 3,000 حرف.

ما يجب فعله: اختصره، أو قسّمه إلى عدة رسائل.

too_many_recipients#

‏HTTP 400. تحتوي دفعة على أكثر من 1,000 مستلم في to.

ما يجب فعله: قسّم القائمة إلى دفعات لا تتجاوز كل منها 1,000، لكل دفعة Idempotency-Key خاص بها.

invalid_datetime#

‏HTTP 400. وقت (send_at أو expires_at أو since أو until) ليس بصيغة ISO 8601 مع فارق التوقيت (offset).

ما يجب فعله: اكتبه مثل 2026-10-20T09:30:00+05:30 أو 2026-10-20T04:00:00Z. يُرفض الوقت الذي ليس له فارق توقيت، مثل 2026-10-20 09:30، لأنه ملتبس. وفي سلسلة الاستعلام (query string)، اكتب + على شكل %2B.

invalid_phone#

‏HTTP 422. رقم هاتف (to.phone، أو phone عند ربط رقم) ليس رقمًا صالحًا بالصيغة الدولية مع +.

ما يجب فعله: اكتبه مع + ورمز الدولة، مثل ‎+919876543210. المسافات والشرطات مقبولة؛ أما الصفر البادئ (0) بدلًا من رمز الدولة فغير مقبول.

invalid_username#

‏HTTP 422. ‏to.username ليس اسم مستخدم Telegram.

ما يجب فعله: اكتب ‎@name، أو رابط t.me/name، أو tg: متبوعًا بمعرّف مستخدم. راجع المستلمون.

username_needs_telegram#

‏HTTP 422. لا يمكن الإرسال إلى اسم مستخدم Telegram إلا من حساب Telegram، وfrom رقم WhatsApp (أو، عند عدم إرسال from، لا يوجد حساب Telegram متصل واحد بالضبط).

ما يجب فعله: اجعل قيمة from معرّف حساب Telegram، أو أرسل إلى رقم هاتف بدلًا من ذلك.

contact_not_found#

‏HTTP 422. لا توجد جهة اتصال بهذا to.contact_id في مساحة العمل.

ما يجب فعله: تحقّق من المعرّف (مثل contact_id لرسالة سابقة)، أو أرسل إلى to.phone بدلًا من ذلك.

media_not_found#

‏HTTP 422 عند إرسال رسالة أو إنشاء تذكير مع media.media_id؛ وHTTP 404 في GET أو DELETE /media/{id}. لا يوجد ملف بهذا المعرّف في مكتبة الوسائط لمساحة العمل، أو أنه حُذف.

ما يجب فعله: تحقّق من المعرّف باستخدام عرض الملفات، أو ارفع الملف مرة أخرى.

invalid_media_url#

‏HTTP 422. ‏media.url ليس رابط http أو https عامًا: إمّا أنه مشوّه، أو يشير إلى عنوان خاص أو محلي.

ما يجب فعله: استخدم رابطًا يستطيع أي شخص على الإنترنت فتحه، أو ارفع الملف وأرسله عبر media_id.

time_in_past#

‏HTTP 422. انقضى وقت send_at أو expires_at بالفعل.

ما يجب فعله: تحقّق من الوقت ومن فارق توقيته. للإرسال الآن، لا ترسل send_at.

number_not_found#

‏HTTP 422 عندما لا يكون from (أو number_id عند الربط) رقمًا من أرقام مساحة العمل هذه؛ وHTTP 404 في GET /numbers/{id}، وكذلك عندما لا يُسمح للمفتاح باستخدام ذلك الرقم.

ما يجب فعله: احصل على id الصحيح من عرض الأرقام.

from_required#

‏HTTP 422. ‏from مفقود، وليس لدى مساحة العمل أي رقم متصل أو لديها أكثر من رقم، فلا يتضح أيّها يجب أن يرسل. (وبالنسبة إلى مفتاح مقيّد ببعض الأرقام: الرقم المتصل الوحيد ليس من أرقامه.)

ما يجب فعله: أرسل from مع id الرقم الذي سيُرسَل منه.

number_not_allowed#

‏HTTP 403. المفتاح مقيّد ببعض الأرقام، وهذا الطلب يحتاج إلى رقم آخر: from رقم آخر، أو تذكير لا يحدد أحد أرقامه، أو طلب ربط يضيف رقمًا أو يحدد رقمًا آخر، أو أن الطلب يدير نقاط استقبال webhook.

ما يجب فعله: استخدم أحد أرقام المفتاح (number_ids في GET /me)، أو مفتاحًا غير مقيّد.

no_credits#

‏HTTP 402. لم تتبقَّ لمساحة العمل رسائل في باقتها. وفي الدفعة، يذكر requested وremaining عدد الرسائل المطلوبة وعدد المتبقية.

ما يجب فعله: أرسل رسائل أقل، أو اشترِ باقة أو مزيدًا من الرسائل؛ فالباقات المدفوعة ترسل رسائل غير محدودة. راجع عند نفاد رسائلك.

account_disabled#

‏HTTP 403. حساب مالك مساحة العمل معطّل، لذا لا تستطيع مساحة العمل الإرسال.

ما يجب فعله: تواصل مع الدعم.

number_daily_cap_reached#

‏HTTP 429. أرسل الرقم المُرسِل 1,000 رسالة خلال آخر 24 ساعة (الاستخدام العادل)، أو أن الدفعة لن تتسع لما تبقّى: يذكر requested وroom العدد.

ما يجب فعله: أرسل الباقي لاحقًا، أو من رقم آخر.

message_rejected#

‏HTTP 422. تعذّر وضع الرسالة في قائمة الانتظار؛ ويذكر message السبب. لم يُحفظ شيء.

ما يجب فعله: أصلح ما يصفه message وأرسل مرة أخرى.

message_not_found#

‏HTTP 404. لا توجد رسالة بهذا المعرّف لهذا المفتاح: إمّا أنها غير موجودة، أو تخص مساحة عمل أخرى، أو أُرسلت من رقم لا يُسمح للمفتاح باستخدامه. لا يرى مفتاح الاختبار إلا رسائل الاختبار الخاصة به، ولا يراها المفتاح المباشر أبدًا.

ما يجب فعله: تحقّق من المعرّف، ومن أنك تستخدم نوع المفتاح نفسه (مباشر أو اختبار) الذي أنشأ الرسالة.

not_cancellable#

‏HTTP 409. لا يمكن إلغاء إلا رسالة منتظرة (queued أو scheduled)، وهذه الرسالة لم تعد منتظرة. يذكر status في الخطأ حالتها الآن، مثل sent أو cancelled.

ما يجب فعله: لا يوجد ما يُلغى. لا يمكن استرجاع رسالة أُرسلت.

التذكيرات#

invalid_cron#

‏HTTP 400. ‏schedule.cron ليس تعبير cron من 5 أجزاء، أو يصف وقتًا لا يأتي أبدًا (مثل 31 فبراير).

ما يجب فعله: اكتب الدقيقة، والساعة، ويوم الشهر، والشهر، ويوم الأسبوع، مثل 0 9 * * 1 لأيام الاثنين في الساعة 09:00. راجع الجدول الزمني.

invalid_timezone#

‏HTTP 400. ‏schedule.timezone ليس اسم منطقة زمنية من IANA.

ما يجب فعله: استخدم اسمًا مثل Asia/Kolkata أو Europe/London أو America/New_York، لا اختصارًا مثل IST ولا فارق توقيت مثل ‎+05:30. راجع مرجع المناطق الزمنية.

number_not_connected#

‏HTTP 422. ‏from الخاص بالتذكير ليس رقمًا متصلًا من أرقام مساحة العمل هذه.

ما يجب فعله: اربط الرقم أولًا، أو اختر رقمًا متصلًا، أو لا ترسل from (null) ليرسله أي رقم متصل.

reminder_not_found#

‏HTTP 404. لا يوجد تذكير بهذا المعرّف: إمّا أنه غير موجود، أو حُذف، أو يُرسَل من رقم لا يُسمح للمفتاح باستخدامه.

ما يجب فعله: تحقّق من المعرّف باستخدام عرض التذكيرات.

الوسائط#

file_too_large#

‏HTTP 413. الملف المرفوع أكبر من 64 ميغابايت.

ما يجب فعله: اضغطه أو قسّمه؛ وفي حالة الفيديو، اخفض دقته.

unsupported_file_type#

‏HTTP 415. لا يمكن إرسال نوع الملف على WhatsApp. يُقرأ النوع من الامتداد في نهاية اسم الملف.

ما يجب فعله: راجع الأنواع التي يمكنك رفعها، وأبقِ الامتداد في الاسم (price-list.pdf وليس price-list).

storage_full#

‏HTTP 422. لا يتسع الملف في مكتبة الوسائط لمساحة العمل وفق باقتها. يذكر used وlimit المساحة المستخدمة والمسموح بها، بالبايت.

ما يجب فعله: احذف الملفات التي لم تعد تحتاج إليها، أو انتقل إلى باقة فيها مساحة تخزين أكبر.

media_in_use#

‏HTTP 409. لا يمكن حذف الملف بعد: لا يزال هناك ما سيرسله (رسالة منتظرة، بما فيها رسائل الحملات، أو تذكير نشط، أو مشغّل Google Sheets نشط). يذكر count العدد.

ما يجب فعله: ألغِ هذه العناصر أو غيّرها أولًا، أو انتظر حتى تُرسَل الرسائل المنتظرة.

upload_failed#

‏HTTP 502. تعذّر حفظ الملف من جهتنا.

ما يجب فعله: حاول مرة أخرى، مع Idempotency-Key نفسه.

فحص الأرقام#

no_valid_numbers#

‏HTTP 422. لا يوجد في numbers أي إدخال هو رقم هاتف. يذكر skipped عدد الإدخالات.

ما يجب فعله: أرسل الأرقام بالصيغة الدولية مع +، رقمًا واحدًا لكل إدخال، مثل ‎+919876543210.

too_many_numbers#

‏HTTP 422. يحتوي الفحص على أرقام أكثر مما يُسمح به لفحص واحد: أكثر من 10,000 إدخال في الطلب، أو أرقام أكثر مما تسمح به الباقة لكل فحص. يذكر count وlimit العدد.

ما يجب فعله: قسّم القائمة إلى عدة فحوص. راجع حدود الباقة.

number_check_quota_reached#

‏HTTP 422. سيتجاوز الفحص عدد فحوص الأرقام المسموح به في الباقة لفترة الفوترة هذه. يذكر requested وused وlimit العدد.

ما يجب فعله: افحص أرقامًا أقل، أو انتظر فترة الفوترة التالية، أو رقِّ الباقة.

number_check_not_found#

‏HTTP 404. لا يوجد فحص أرقام بهذا المعرّف في مساحة العمل.

ما يجب فعله: تحقّق من المعرّف باستخدام عرض الفحوص.

الأرقام#

plan_required#

‏HTTP 403. لا تتضمن باقة مساحة العمل ما يحتاج إليه هذا الطلب: API رمز QR لربط رقم، أو التذكيرات لإنشاء تذكير أو تغييره أو استئنافه، أو التحقق من الأرقام لبدء فحص أرقام.

ما يجب فعله: يمكن للمالك الترقية من صفحة الأسعار. وقراءة ما هو موجود بالفعل تعمل في أي باقة.

number_limit_reached#

‏HTTP 403. لا تتسع الباقة لرقم آخر.

ما يجب فعله: أعد ربط رقم موجود باستخدام number_id، أو أزل رقمًا لم تعد تستخدمه، أو رقِّ الباقة.

already_connected#

‏HTTP 409. الرقم متصل بالفعل.

ما يجب فعله: لا شيء: يمكنك الإرسال منه. تحقّق من ذلك باستخدام جلب رقم.

connect_in_progress#

‏HTTP 409. يجري ربط هذا الرقم الآن. يذكر number_id في الخطأ أيّ رقم هو.

ما يجب فعله: استطلع GET /numbers/{id} لهذا الرقم بدلًا من الطلب مرة أخرى. وبعد 10 دقائق دون مسح الرمز، يمكنك الطلب مرة أخرى.

Webhooks#

invalid_webhook_url#

‏HTTP 422. ‏url ليس عنوان https:// عامًا: إمّا أنه http://، أو مشوّه، أو يشير إلى عنوان خاص أو محلي.

ما يجب فعله: استخدم عنوان https:// يستجيب عليه خادمك من الإنترنت. وللاختبار على حاسوبك، استخدم خدمة نفق (tunnel) تمنحك عنوان https:// عامًا.

webhook_limit_reached#

‏HTTP 403. لدى مساحة العمل بالفعل 5 نقاط استقبال webhook.

ما يجب فعله: أزل نقطة لم تعد تستخدمها. يمكن لنقطة استقبال واحدة أن تتلقى كل أنواع الأحداث.

webhook_not_found#

‏HTTP 404. لا توجد نقطة استقبال webhook بهذا المعرّف: إمّا أنها غير موجودة أو أُزيلت. ويُعيد اختبار نقطة استقبال متوقفة أو تبديل سرّها هذا الخطأ أيضًا؛ أما قراءتها فتُظهر active: false.

ما يجب فعله: تحقّق من المعرّف باستخدام عرض نقاط الاستقبال. وإذا كانت قد توقفت، فأضفها مرة أخرى.

وضع الاختبار#

test_mode_unsupported#

‏HTTP 403. يمكن لمفتاح الاختبار (wbz_test_…) أن يرسل رسائل الاختبار ويقرأها ويلغيها، وأن يقرأ بقية مساحة العمل، لكنه لا يستطيع تغيير أي شيء آخر: ربط رقم، أو إنشاء التذكيرات أو تغييرها أو حذفها، أو رفع الوسائط أو حذفها، أو بدء فحص أرقام، أو إدارة نقاط استقبال webhook. كما أن عامل التصفية status في GET /messages غير مدعوم لمفاتيح الاختبار.

ما يجب فعله: استخدم مفتاحًا مباشرًا (wbz_live_…) لهذه الطلبات. راجع وضع الاختبار.