الأخطاء

تجمع هذه الصفحة الأخطاء الموصوفة في بقية الصفحات لتعالجها في مكان واحد. ترد الواجهة على كل خطأ بغلاف JSON واحد، أما نقاط OAuth فتستخدم صيغة RFC 6749.

غلاف الخطأ في الواجهة

{
  "error": { "code": "forbidden", "message": "Missing scope: orders:write" },
  "meta": { "request_id": "8f2c1a9d4b7e6035", "api_version": "v1" }
}

error.code ثابت ومخصص لبرنامجك. error.message موجه للبشر وقد يتغير. اذكر meta.request_id عندما تراسل DZBuild بخصوص استدعاء ما. تضيف بعض الأخطاء حقولاً داخل error، مثل retry_after في الرد 429.

أكواد حالة الواجهة

الحالة	error.code	الرسالة	السبب والإجراء
400	bad_request	متغيرة	ترويسة Idempotency-Key مفقودة أو غير صحيحة في طلب POST أو PATCH أو DELETE، أو المتن ليس JSON صالحاً، أو معرّف في المسار ليس رقماً. صحّح الطلب وأرسل مفتاحاً جديداً.
401	unauthorized	Missing Authorization header	لا توجد ترويسة Authorization.
401	unauthorized	Unsupported Authorization scheme	الترويسة لا تبدأ بـ Bearer.
401	unauthorized	Invalid or revoked API key	الرمز خاطئ، أو أزال التاجر تطبيقك. تعامل معه كإزالة ما لم تكن متأكداً من غير ذلك.
402	no_credit		محفظة WhatsApp في المتجر فارغة. لم يُصطف شيء ولم يُخصم شيء. إعادة المحاولة لا تفيد؛ يعبّئ التاجر الرصيد من لوحة التحكم.
402	quota_exceeded		بلغ المتجر حصة شهرية من الطلبات حددتها DZBuild له. إعادة المحاولة لا تفيد.
403	forbidden	Missing scope: <scope>	الرمز لا يحمل الصلاحية التي تحتاجها نقطة الوصول. بعض عمليات الكتابة تحتاج صلاحية القراءة أيضاً؛ انظر الصلاحيات.
403	forbidden	Apps cannot use this endpoint	/v1/keys و/v1/webhooks و/v1/changes مغلقة أمام رموز التثبيت.
403	app_uninstalled	This app is no longer installed on this store	التثبيت لم يعد نشطاً. توقف عن استخدام الرمز واحذف بيانات المتجر.
403	app_suspended	This app has been suspended by DZBuild	أوقفت DZBuild التطبيق أو رفضته. تعود الاستدعاءات إلى العمل بعد رفع الإيقاف.
403	app_not_approved	This app is in test mode and only runs on its developer's stores	لم يُقبل التطبيق بعد والمتجر ليس ملكك.
403	app_plan_required	This app requires the ... plan	خطة المتجر، أو خطة مدفوعة منتهية، أدنى من الخطة الدنيا للتطبيق. أخبر التاجر بالخطة المطلوبة.
403	addon_not_active		خاص بـ WhatsApp. لم يفعّل التاجر إضافة WhatsApp Sender.
403	plan_required		خاص بأقسام الصفحة الرئيسية. الكتابة تترك أقساماً أكثر مما تسمح به خطة المتجر. يحمل error قيمتي plan وcap.
404	not_found		لا يوجد سجل بهذا المعرّف في هذا المتجر.
404	section_not_found		خاص بأقسام الصفحة الرئيسية. لا يوجد قسم بهذا الرقم في الصفحة الرئيسية للمتجر.
409	already_sent		خاص بـ WhatsApp. أُرسل هذا القالب من قبل لهذا الطلب. يحمل error قيمتي id وstatus للرسالة الموجودة.
409	write_conflict		خاص بأقسام الصفحة الرئيسية. غيّرت كتابة أخرى التخطيط قبلك، أو version المرسلة مع PUT ليست الحالية. عندما يحمل error قيمتي sections وversion أعد المحاولة انطلاقاً منهما، وإلا فاقرأ التخطيط من جديد.
422	idempotency_key_reuse		أُرسل المفتاح Idempotency-Key نفسه بطريقة أو مسار أو متن مختلف. مفتاح واحد لكل عملية.
422	أكواد WhatsApp		unknown_template وinvalid_language وinvalid_number وsuppressed وtemplate_not_approved وempty_param. لم يُخصم شيء. صحّح السبب وأعد الاستدعاء بمفتاح جديد. انظر واجهة WhatsApp.
422	أكواد أقسام الصفحة الرئيسية		invalid_settings (تذكر error.fields الإعدادات المرفوضة، ومع PUT إعدادات أول قسم مرفوض) وinvalid_section_type وlimit_reached وinvalid_order وno_changes. صحّح الطلب وأعد الاستدعاء بمفتاح جديد. انظر أقسام الصفحة الرئيسية.
429	rate_limited	Per-minute API limit exceeded for this app install	نفدت ميزانية تثبيتك، 120 طلباً في الدقيقة. انتظر retry_after ثانية (موجودة أيضاً في ترويسة Retry-After) ثم أعد الإرسال بالمفتاح Idempotency-Key نفسه.
429	rate_limited	Per-minute API limit exceeded for this store	نفدت ميزانية المتجر المشتركة. المعالجة نفسها.
429	rate_limited	Per-minute API limit exceeded for this key	سقف البوابة، 600 طلب في الدقيقة لكل متجر. المعالجة نفسها.
429	too_many_concurrent		عمليات مكلفة كثيرة في الوقت نفسه (رفع الصور، استدعاءات شركات التوصيل، كتابات أقسام الصفحة الرئيسية). قيمة retry_after هي 5 ثوانٍ.
500	send_failed		خاص بـ WhatsApp. تعذّر اصطفاف الرسالة. أعد المحاولة لاحقاً.
502	server_error	Key lookup failed, retry shortly	لم تستطع البوابة التحقق من الرمز لدى DZBuild. أعد المحاولة بعد انتظار قصير بالمفتاح Idempotency-Key نفسه.

إعادة المحاولة أم لا

الرد	إعادة المحاولة	باستخدام
429	نعم، بعد retry_after ثانية	المفتاح Idempotency-Key نفسه
5xx و502	نعم، بعد انتظار قصير	المفتاح Idempotency-Key نفسه؛ هذه الردود لا تُحفظ أبداً، لذلك يُنفَّذ الطلب
400 و401 و403 و404 و422	لا. صحّح السبب أولاً	مفتاح Idempotency-Key جديد، لأن الرد 4xx المحفوظ يُعاد لمدة 24 ساعة
402	لا. على التاجر أن يتصرف
409 already_sent	لا. الرسالة موجودة
409 write_conflict	نعم، انطلاقاً من sections وversion في error أو بعد قراءة التخطيط من جديد	مفتاح Idempotency-Key جديد

أخطاء OAuth

قبل أن تطابق DZBuild قيمتي client_id وredirect_uri، تعرض صفحة خطأ للتاجر ولا تعيد التوجيه أبداً. بعد ذلك تعيد التوجيه إلى redirect_uri مع معامل error:

error	السبب
unsupported_response_type	قيمة response_type ليست code.
invalid_request	state مفقود أو أطول من 1024 حرفاً، أو code_challenge ليس 43 حرفاً بصيغة base64url، أو code_challenge_method ليس S256.
invalid_scope	صلاحية غير مسجلة على التطبيق أو غير مسموح بها للتطبيقات، أو معامل scope أطول من 512 حرفاً.
access_denied	ضغط التاجر على رفض.

ترد نقطة الرمز بصيغة JSON تحمل error وerror_description:

HTTP	error	السبب
401	invalid_client	client_id أو client_secret مفقود أو خاطئ.
400	unsupported_grant_type	قيمة grant_type ليست authorization_code.
400	invalid_grant	كود مجهول أو منتهٍ أو مستعمل، أو كود صادر لتطبيق آخر، أو redirect_uri مختلف، أو مُحقِّق لا يطابق التحدي، أو تعذّر تثبيت أي متجر من المتاجر المختارة.
500	server_error	عطل في المنصة. أعد توجيه التاجر إلى خطوة التفويض من جديد.
403	لا يوجد، الجسم صفحة HTML	الطلب لا يحمل الترويسة User-Agent، وdzbuild.com يجيب على أي طلب POST بدونها بصفحة تحقق بدل JSON. أرسلها، مثلا my-app/1.0 (+https://example.com).

الكود الذي طُلب استبداله يُستهلك حتى لو فشل التبادل، لذلك ابدأ طلب تفويض جديداً بدل إعادة المحاولة بالكود نفسه. الترتيب الكامل للفحوص وصفحات الخطأ في صفحة OAuth.

إخفاقات إرسال إشعارات webhook

ينجح الإرسال عندما يرد خادمك بـ 2xx خلال 10 ثوانٍ. أي حالة أخرى، أو إعادة توجيه، أو انتهاء مهلة، أو خطأ اتصال يُعدّ محاولة فاشلة. تحاول DZBuild كل إرسال حتى 5 مرات بفترات انتظار متزايدة، ثم تعلّمه كمتروك. بعد 10 محاولات فاشلة متتالية على تثبيت واحد يُعطَّل رابطه؛ اضغط على تحقق في منصة المطورين لإعادة تفعيله. التفاصيل والجدول في صفحة إشعارات Webhook.

يجب أن يرد تحققك أنت بـ 401 عندما يفشل التوقيع أو فحص الطابع الزمني. ولأن ذلك ليس رداً 2xx، تعدّه DZBuild محاولة فاشلة وتعيد المحاولة؛ الطلب الذي يفشل في التحقق دائماً ليس من DZBuild، أو أن سرّ التوقيع لديك قديم.