الأخطاء

بنية الخطأ:

{ "error": { "code": "...", "message": "...", "retry_after": 12 },
  "meta": { "request_id": "...", "api_version": "v1", "edge": true } }

الحقلان meta.request_id وmeta.api_version موجودان دائمًا. أما retry_after فيظهر مع 429 فقط. والحقل meta.edge يكون true فقط عندما تكتب البوابة في api.dzbuild.app الرد بنفسها، كرفض المصادقة أو تجاوز حد المعدل أو فشل التحقق من المفتاح، بدلًا من تمرير رد المنصة كما هو.

الكود	HTTP	المعنى
unauthorized	401	رأس Authorization مفقود أو غير صالح
forbidden	403	موثَّق ولكن يفتقر إلى الصلاحية، أو إلى تسجيل في البرنامج التجريبي، أو إلى خطة Enterprise سارية (مفاتيح API الخاصة بالتاجر تتطلب Enterprise، أما رموز التطبيقات المثبّتة فتعمل مع كل الخطط). ويتلقاه رمز التطبيق أيضًا، مع الرسالة Apps cannot use this endpoint، على /v1/keys و/v1/webhooks و/v1/changes
app_uninstalled	403	رمز تطبيق: التطبيق لم يعد مثبّتًا على هذا المتجر
app_suspended	403	رمز تطبيق: علّقت DZBuild التطبيق أو رفضته
app_not_approved	403	رمز تطبيق: التطبيق في وضع الاختبار، وهذا المتجر لا يعود إلى مطوّره
app_plan_required	403	رمز تطبيق: خطة المتجر أدنى من الخطة الدنيا التي يشترطها التطبيق؛ تذكر message اسم الخطة
not_found	404	المورد غير موجود أو لا ينتمي إلى متجرك
bad_request	400	خطأ في التحقق؛ راجع message
idempotency_key_reuse	422	سبق استعمال Idempotency-Key مع طريقة أو مسار أو محتوى مختلف؛ أرسل مفتاحًا جديدًا
method_not_allowed	405	المسار موجود لكن لطريقة HTTP أخرى
payload_too_large	413	جسم الطلب أكبر من 1 ميغابايت
rate_limited	429	تجاوز الحد لكل دقيقة؛ يُرفق رأس Retry-After. ولرموز التطبيقات أيضًا حد خاص بكل تثبيت قدره 120 طلبًا في الدقيقة، يُفحَص قبل حد المتجر
too_many_concurrent	429	عدد كبير من النداءات المكلفة قيد التنفيذ (الصور، توليد الذكاء الاصطناعي، نداءات شركات التوصيل، كتابات أقسام الصفحة الرئيسية)؛ أعد المحاولة بعد ثوانٍ
quota_exceeded	402	تم بلوغ الحد الشهري؛ ارقَ إلى خطة أعلى أو انتظر
server_error	500	خطأ غير متوقع في الخادم؛ آمن لإعادة المحاولة على النداءات الـ idempotent
server_error	502	تعذّر على api.dzbuild.app التحقق من مفتاحك لدى المنصة؛ أعد المحاولة بعد لحظات

كائن details محجوز لإخراج تحقُّق مُهيكَل مستقبلًا. لا توجد نقطة نهاية تُصدره اليوم، فلا تبنِ منطقك عليه.

إعادة محاولة عملية كتابة فاشلة

تُخزَّن استجابة 4xx الصادرة عن معالج عملية كتابة مقابل Idempotency-Key الخاص بك لمدة 24 ساعة، على https://api.dzbuild.app وعلى الاسم البديل dzbuild.com/api/v1 على حد سواء: إعادة المحاولة بالمفتاح نفسه والمحتوى نفسه تعيد الخطأ ذاته موسومًا بـIdempotency-Replay: 1، دون تنفيذ أي شيء من جديد. صحِّح الطلب وأرسله بمفتاح جديد، فالمفتاح القديم يجيب بـ 422 idempotency_key_reuse على المحتوى المعدَّل. أما حالات الرفض التي تقع قبل تشغيل المعالج، ومنها 401 وردود 403 الخاصة بالبرنامج التجريبي والخطة ورموز app_*، و429، وغياب Idempotency-Key أو خطأ تنسيقه، فلا تُخزَّن، وكذلك استجابات 5xx، لذا يمكن إعادة المحاولة بالمفتاح نفسه بأمان. انظر Idempotency.

أرفق meta.request_id دائمًا عند التواصل مع الدعم.