الانتظار والأخطاء وإعادة المحاولة

يُرَد على طلب الإرسال فورًا بـ 202 وstatus: "queued". بعدها تخرج الرسالة كما يرسلها شخص حقيقي، ولذلك قد تنتظر. كل قاعدة إما أن تؤجّل الرسالة (فتبقى queued وتُرسل من تلقاء نفسها) أو تُفشلها (status: "failed"، والسبب في error). توضّح هذه الصفحة أي القواعد تؤجّل وأيها تُفشل، وكم قد يطول الانتظار، وما الذي يعيد نظامك محاولته.

أين ترى السبب

الرسالة الفاشلة تذكر السبب في error بكلمات بسيطة: في GET /v1/messages/{id}، وفي ويب هوك message.status، وفي لوحة التحكم تحت الرسالة في محادثتها وفي «سجل الرسائل» (ضمن «للمطورين»). أما error_code فيذكر السبب نفسه كقيمة ثابتة يقرؤها نظامك: راجع رموز الأخطاء.
الرسالة المنتظرة تبقى queued حتى تُرسل، بلا error. ويذكر error_code ما تنتظره، ثم يعود null بعد إرسالها. ويعرض GET /v1/instances/{id} وضع الرقم اليوم ضمن protection: حدود اليوم وما استُخدم منها، وtimezone الخاص به، وضمن new_chats هل المحادثات الجديدة متوقفة مؤقتًا، ولماذا، وحتى متى.

ما الذي يؤجّل الرسالة

الرسالة المؤجّلة لا تحتاج منك شيئًا. تُرسل حين يأتي دورها.

سبب الانتظار	مدة الانتظار
دورها. يرسل الرقم الواحد رسالة واحدة في كل مرة، بفاصل يتوقف على من تُرسل إليه (راجع الإيقاع)	ثوانٍ؛ ولشخص جديد حتى دقيقة، ومن 5 إلى 10 دقائق بعد كل عاشر شخص جديد
الليل. لا تُرسل رسالة إلى من لم يكتب من قبل من 22:00 إلى 08:00 بالتوقيت المحلي للرقم (أو في ساعات الهدوء التي تحددها)	حتى الصباح
شخص واحد ورسائل كثيرة. تُرسل 4 رسائل في الساعة على الأكثر إلى من لم يرد، و10 ما دام يتحادث معك	حتى تمر الساعة، أو حتى يكتب
رسالة سابقة إلى المحادثة نفسها ما زالت تنتظر. تُرسل الرسائل إلى الشخص الواحد بالترتيب الذي أرسلتها به	حتى تُرسل تلك الرسالة
مجموعة واحدة ورسائل كثيرة: 20 رسالة في الساعة على الأكثر للمجموعة الواحدة	حتى تمر الساعة
الرقم يعيد الاتصال بواتساب	دقيقة في كل مرة؛ وإن بقي الرقم غير متصل تفشل الرسالة
واتساب يقيّد الرقم، أو رفض للتو إحدى رسائله. تُرسل الردود فقط في هذه الأثناء: وكل ما عداها ينتظر	حتى ينتهي التقييد (ساعة على الأقل بعد الرفض) إن كان ذلك خلال 6 ساعات؛ وإن طال أكثر تفشل الرسالة مع ذكر السبب
ملف مُعطى عبر `url` لم يُجب خادمه، أو أجاب بخطأ من الخادم	3 محاولات بفاصل دقيقتين (2) بينها، ثم تفشل

ما الذي يُفشل الرسالة

الرسالة الفاشلة لن تُرسل من تلقاء نفسها. اقرأ error: فهو يذكر ما عليك فعله.

الرقم لا يستطيع الإرسال: غير متصل، أو متوقف، أو الحساب موقوف، أو رُبط هاتف مختلف بعد وضع الرسالة في الانتظار.
الشخص: كتب «STOP»، أو رقمه ليس على واتساب.
حدود اليوم: استُنفد حد الرقم من الأشخاص الجدد لليوم، أو رسائل الإحماء اليومية التي ليست ردودًا، أو رسائل المجموعات (200 في اليوم) أو منشورات القنوات (30 في اليوم). ويقول السبب «Try again tomorrow» (حاول مرة أخرى غدًا).
شخص جديد لم يرد: أكثر من متابعتين (2) في اليوم، أو رسالة أولى جديدة قبل مرور 7 أيام. ويذكر السبب التاريخ الذي يمكن إرسالها فيه.
محتوى الرسالة الأولى: موقع أو بطاقة جهة اتصال أو ملصق أو استطلاع؛ أو رابط http://، أو رابط فقط. وكذلك أكثر من 600 حرف، أو نص أو ملف بدأ 5 محادثات في ذلك اليوم.
المحادثات الجديدة متوقفة مؤقتًا: أوقفها واتساب لأكثر من 6 ساعات، أو أوقفناها نحن، أو لأن لا أحد تقريبًا يرد على الرسائل الأولى للرقم. أما الردود فتُرسل.
الملف: تعذّر جلبه، أو حجمه أكبر من المسموح، أو الملصق ليس صورة WebP.
رفضها واتساب، أو لم يؤكدها في الوقت المناسب. في الحالة الثانية ربما وصلت: راجع المحادثة قبل إرسالها مرة أخرى.
رمز OTP الذي لا يمكن إرساله خلال دقيقتين (2) يفشل فورًا: الرمز المتأخر لا فائدة منه.
ألغيتها أنت قبل أن تُرسل.

القواعد نفسها في كيف يحمي الإرسال رقمك.

رموز أخطاء الرسالة

error مكتوب للناس، وقد تتغير كلماته. أما error_code فلنظامك: قيمة ثابتة واحدة لكل سبب، على الرسالة في الـ API وفي حدث message.status. في رسالة failed هو سبب فشلها. وفي رسالة queued هو ما تنتظره الرسالة، ولا يُرسل حدث عن الانتظار. الرسالة التي فشلت قبل إضافة الرموز لا رمز لها. وقد تُضاف قيم جديدة، فإن وجدت قيمة لا تعرفها فاعتمد على error وحده.

الرمز	معناه	الرسالة
`instance_not_connected`	الرقم غير متصل بواتساب	تفشل
`instance_stopped`	الرقم متوقف. شغّله ليرسل	تفشل
`instance_reconnecting`	الرقم يعيد الاتصال بواتساب	تنتظر
`number_on_another_instance`	رقم واتساب الذي مُسح تابع لرقم آخر لديك، فلم يُربط هنا	تفشل
`account_suspended`	الحساب موقوف	تفشل
`phone_changed`	رُبط هاتف مختلف بعد وضع الرسالة في الانتظار أو جدولتها	تفشل
`opted_out`	كتب الشخص «STOP» أو ما يشبهها	تفشل
`opt_out_unconfirmed`	تعذّر على واتساب تحديد هل هذا الشخص ممن طلبوا التوقف	تنتظر
`not_on_whatsapp`	رقم الهاتف ليس على واتساب	تفشل
`no_number`	الرسالة موجّهة بمعرّف محادثة خاص، ورقم الشخص لم يعد معروفًا، ولم يكتب مؤخرًا	تفشل
`quiet_hours`	الوقت ليل بتوقيت الرقم، ولا تُرسل رسائل إلى أشخاص جدد ليلًا	تنتظر
`pacing`	الفاصل قبل رسالة الرقم التالية	تنتظر
`earlier_message_waiting`	رسالة سابقة إلى المحادثة نفسها تُرسل أولًا	تنتظر
`per_minute_limit`	سقف رسائل الرقم في الدقيقة	تنتظر
`per_person_limit`	عدة رسائل إلى هذا الشخص في الساعة الأخيرة بقيت بلا رد	تنتظر
`per_group_limit`	رسائل كثيرة أُرسلت إلى هذه المجموعة في الساعة الأخيرة	تنتظر
`daily_new_people_limit`	استُنفد حد الرقم من الأشخاص الجدد لليوم	تفشل
`daily_lookup_limit`	تحقق الرقم اليوم من أقصى عدد مسموح من الأرقام الجديدة على واتساب	تفشل
`daily_volume_limit`	استُنفدت رسائل اليوم التي ليست ردودًا: بسبب الإحماء، أو الحد الذي وضعته أنت	تفشل
`daily_group_limit`	استُنفدت رسائل المجموعات لليوم	تفشل
`daily_channel_limit`	استُنفدت منشورات القنوات لليوم	تفشل
`unanswered_follow_ups`	لم يرد الشخص، واستُنفدت متابعات اليوم له	تفشل
`not_answered_yet`	لم يرد الشخص على آخر رسالة؛ ويذكر `error` التاريخ الذي يمكن مراسلته فيه من جديد	تفشل
`first_message_type`	الرسالة الأولى لا يمكن أن تكون موقعًا أو بطاقة جهة اتصال أو ملصقًا أو استطلاعًا	تفشل
`first_message_too_long`	الرسالة الأولى أطول من المسموح	تفشل
`insecure_link`	رسالة إلى شخص جديد تحتوي على رابط `http://`	تفشل
`link_only`	الرسالة الأولى رابط فقط	تفشل
`same_first_message`	النص نفسه، أو الملف والتعليق نفسهما، بدأ العدد المسموح من المحادثات لليوم	تفشل
`new_chats_paused`	أوقفنا المحادثات الجديدة من الرقم. أما الردود فتُرسل	تفشل
`few_replies`	لا أحد تقريبًا يرد على الرسائل الأولى للرقم، لذا أُوقفت المحادثات الجديدة	تفشل
`whatsapp_restricted`	واتساب يقيّد الرقم، أو رفض للتو إحدى رسائله	تنتظر
`whatsapp_quota`	الرقم اقترب من حصة واتساب من المحادثات الجديدة أو بلغها	تنتظر
`whatsapp_refused`	رفض واتساب الرسالة. إرسالها مرة أخرى لن يفيد	تفشل
`whatsapp_unreachable`	واتساب لم يُجب	تنتظر
`may_have_been_delivered`	لم يؤكدها واتساب في الوقت المناسب. راجع المحادثة قبل إرسالها مرة أخرى	تفشل
`file_unavailable`	تعذّر جلب الملف من `url`، أو حجمه أكبر من المسموح	تنتظر
`file_missing`	ملف الرسالة لم يعد محفوظًا لدينا	تفشل
`invalid_sticker`	يجب أن يكون الملصق صورة WebP بحجم 1 ميجابايت على الأكثر	تفشل
`file_too_large`	في رسالة استلمتها: كان ملفها أكبر من 100 ميجابايت، فلم نحفظه	تبقى `received`، بلا `media`
`otp_too_late`	تعذّر إرسال رسالة الـ OTP خلال مهلتها القصيرة	تفشل
`otp_ended`	انتهى الـ OTP قبل إرسال رمزه	تفشل
`broadcast_stopped`	الرسالة الجماعية التي تتبعها أوقفتها: توقفت مؤقتًا، أو أُلغيت، أو أُوقفت للأمان، أو تعذّر وضع الرسالة في الانتظار. ويأتي دور الشخص من جديد	تفشل
`warmup_stopped`	توقف الإحماء التلقائي قبل إرسال الرسالة	تفشل
`cancelled`	ألغيتها أنت قبل أن تُرسل	تفشل
`not_queued`	تعذّر علينا وضعها في الانتظار. أرسلها مرة أخرى	تفشل

الرسالة التي «تنتظر» تفشل بالرمز نفسه إن تعذّر أن ينتهي الانتظار في الوقت المناسب: راجع أطول انتظار. والطلب الذي يرفضه الـ API مباشرة (409، 422، 429) لا ينشئ رسالة، فلا error_code له: اقرأ message الخاص به.

أطول انتظار

تنتظر الرسالة 24 ساعة على الأكثر، تُحسب من وقت إرسالك لها، أو من send_at إن جدولتها. التأجيل الذي سيمتد إلى آخر 10 دقائق من هذه المدة لا يبدأ أصلًا: تفشل الرسالة حينها، ويذكر error ما أجّلها. وينتهي غالبًا بعبارة «It waited as long as it could, so it was not sent. Send it again if it is still wanted.» (انتظرت أطول مدة ممكنة فلم تُرسل) والرسالة التي ما زالت في الانتظار عند انتهاء الـ 24 ساعة تفشل بعبارة «Could not reach WhatsApp. Please try again.» (تعذّر الوصول إلى واتساب)، أو بملاحظة أنها ربما وصلت.

الإيقاع

يرسل كل رقم رسالة واحدة في كل مرة. بعد أي رسالة، تنتظر التالية فاصلًا يُختار عشوائيًا، حسب من تُرسل إليه:

الرسالة التالية موجّهة إلى	الفاصل قبلها
شخص كتب خلال آخر 24 ساعة (رد)	من 2 إلى 8 ثوانٍ
شخص كتب قبل ذلك، أو مجموعة أو قناة	من 8 إلى 20 ثانية
شخص لم يكتب من قبل	من 30 إلى 60 ثانية بعد آخر رسالة أولى، واستراحة من 5 إلى 10 دقائق بعد كل 10 رسائل

الرسالة إلى شخص أو مجموعة تُظهر أيضًا «يكتب…» من 1 إلى 4 ثوانٍ أولًا. وفوق ذلك كله سقف 20 رسالة في الدقيقة لكل رقم. لذلك تستغرق 100 رد من عشر دقائق إلى خمس عشرة دقيقة. أما 100 رسالة أولى فتستغرق أيامًا: الرقم المربوط حديثًا يمكنه مراسلة 10 أشخاص جدد في اليوم، ويرتفع الحد إلى 50 خلال أول أسبوعين.

الأرقام المختلفة ترسل في الوقت نفسه؛ ولا يبطئ أحدها الآخر.

لا ترسل أسرع مما يرسل الرقم. يقبل الـ API 600 طلب في الدقيقة، ويرسل الرقم نحو 20 رسالة في الدقيقة، فالدفعة الكبيرة لا تصنع إلا طابور انتظار. إذا تجاوز ما لدى الرقم 500 رسالة في الانتظار أو مجدولة، يرد POST /v1/messages إليه بـ 429 مع الرمز backlog_full وRetry-After: أرسل الباقي كلما خرجت هذه الرسائل. الرسائل المجدولة بـ send_at تُحسب مثل المنتظرة. والردود على من كتبوا خلال آخر 24 ساعة تُقبل دائمًا. ولإرسال رسالة واحدة إلى أشخاص كثيرين استخدم رسالة جماعية، فهي تضبط وتيرتها بنفسها.

ما الذي يعيد نظامك محاولته

طلب رُفض (لم تُنشأ رسالة):

الحالة	هل تعيد المحاولة؟
`409`	فقط إن وُجدت ترويسة `Retry-After`: انتظر تلك المدة ثم أرسل الطلب نفسه. وإن لم توجد فاقرأ `message`: مثلًا الرقم غير متصل، أو متوقف.
`429`	نعم، بعد `Retry-After`. السبب حد الطلبات (600 في الدقيقة لكل حساب)، أو امتلاء قائمة انتظار الرقم، أو حد في الباقة أو الأمان يذكره `message`.
`502`, `503`	نعم. واتساب لم يُجب، أو تعذّر علينا قبول الطلب الآن. انتظر `Retry-After` إن وُجد؛ وإلا فانتظر بضع ثوانٍ، ثم مدة أطول في كل مرة.
`401`, `403`, `404`, `422`	لا. أصلح المفتاح أو المعرّف أو الطلب أولًا.

أرسل Idempotency-Key نفسه في كل إعادة محاولة للرسالة الواحدة، حتى لا يتحول ردّان على طلب واحد إلى رسالتين أبدًا. ويقبل POST /v1/otps وPOST /v1/broadcasts الترويسة نفسها أيضًا.

رسالة قُبلت (202) لا تحتاج إعادة محاولة ما دامت queued: الانتظار أمر طبيعي.

رسالة فشلت: لا تُعد إرسالها أبدًا في حلقة تكرار. تكرار رسالة مرفوضة هو النمط الذي يحظره واتساب، وسيرفضها السبب نفسه مرة أخرى. اقرأ error وتصرّف بناءً عليه: انتظر إلى الغد، أو دع الشخص يكتب أولًا، أو أصلح الملف. وحين ترسلها من جديد استخدم Idempotency-Key جديدًا: المفتاح القديم يعيد الرسالة الفاشلة.

رموز أخطاء الـ API

الطلب المرفوض يحمل code بجانب message. قد نحسّن كلمات الرسالة؛ أما الرمز فلا يتغير أبدًا. فاجعل نظامك يتصرف بناءً على الرمز، واعرض الرسالة أو سجّلها.

الرمز	المعنى
`unauthenticated`	لم يُرسل مفتاح API، أو أُبطل المفتاح.
`key_not_allowed`	المفتاح أُنشئ بصلاحيات أقل: للقراءة فقط أو للإرسال فقط، أو لرقم واحد.
`ip_not_allowed`	المفتاح مقيّد بعناوين IP، والطلب جاء من عنوان آخر.
`account_suspended`	الحساب متوقف مؤقتًا أو موقوف؛ ويذكر `message` السبب.
`plan_limit`	استُنفد ما في الباقة من الأرقام أو الرسائل أو المحادثات أو طلبات API.
`feature_not_included`	باقتك، أو تجربتها المجانية، لا تشمل هذه الميزة؛ ويذكر `message` اسمها.
`instance_not_found`	لا يوجد رقم بهذا المعرّف في حسابك.
`message_not_found`	لا توجد رسالة بهذا المعرّف في حسابك.
`chat_not_found`	ليس للرقم محادثة مع هذا الشخص، أو لا يعرفه.
`group_not_found`	لا توجد مجموعة بهذا المعرّف.
`channel_not_found`	لا توجد قناة بهذا المعرّف.
`broadcast_not_found`	لا توجد رسالة جماعية بهذا المعرّف في حسابك.
`otp_not_found`	لا يوجد OTP بهذا المعرّف في حسابك.
`status_not_found`	لا توجد حالة بهذا المعرّف على الرقم.
`not_found`	لا يوجد عنوان كهذا، أو لا شيء آخر بهذا المعرّف.
`not_connected`	الرقم غير متصل بواتساب: متوقف، أو انقطع اتصاله، أو لم يُربط بعد.
`link_refused`	الهاتف الذي مُسح تابع لرقم آخر. فك الربط لتبدأ من جديد.
`whatsapp_restricted`	واتساب يقيّد الرقم، وهذا الطلب سيزيد الأمر سوءًا. انتظر حتى يُرفع التقييد.
`new_chats_paused`	المحادثات الجديدة متوقفة مؤقتًا على الرقم، فلا يستطيع مراسلة أشخاص جدد الآن.
`whatsapp_refused`	رفض واتساب الطلب نفسه؛ ويذكر `message` ما يحتاجه.
`in_progress`	هناك عملية أخرى جارية على الرقم أو الحساب. حاول مرة أخرى بعد بضع ثوانٍ.
`conflict`	غير ممكن في الحالة الراهنة، مثل إلغاء رسالة أُرسلت بالفعل.
`validation_failed`	في الطلب خطأ ما؛ ويذكر `errors` كل حقل.
`wrong_code`	رمز OTP غير صحيح؛ ويذكر `attempts_left` عدد المحاولات المتبقية.
`no_attempts_left`	لم تبقَ للـ OTP محاولات. ابدأ واحدًا جديدًا.
`rate_limited`	طلبات كثيرة جدًا من الحساب في دقيقة واحدة.
`limit_reached`	حد خاص بنقطة اتصال واحدة للرقم أو المفتاح أو الهاتف، بالدقيقة أو الساعة أو اليوم؛ ويذكر `message` أيها.
`backlog_full`	لدى الرقم بالفعل رسائل كثيرة جدًا في الانتظار أو مجدولة. أرسل المزيد كلما خرجت.
`file_budget_used`	استُنفد حد الحساب اليومي من الملفات المضمّنة في الطلب. أرسل الملفات عبر `url`، أو انتظر `Retry-After`.
`busy`	الرقم مشغول بطلبات أخرى تقرأ من واتساب. حاول مرة أخرى بعد بضع ثوانٍ.
`whatsapp_unavailable`	واتساب لم يُجب. حاول مرة أخرى.
`unavailable`	تعذّر علينا قبول الطلب الآن. حاول مرة أخرى.
`person_unknown`	تعذّر على واتساب الآن إخبارنا بالرقم الذي وراء `chat_id` خاص، فلم يُرسل شيء. حاول مرة أخرى.
`server_error`	حدث خطأ من جهتنا. حاول مرة أخرى، وأخبرنا إن استمر.
`bad_request`	تعذّرت قراءة الطلب، مثل طريقة طلب لا يقبلها العنوان.

الانتظار والأخطاء وإعادة المحاولة

أين ترى السبب#

ما الذي يؤجّل الرسالة#

ما الذي يُفشل الرسالة#

رموز أخطاء الرسالة#

أطول انتظار#

الإيقاع#

ما الذي يعيد نظامك محاولته#

رموز أخطاء الـ API#