الأخطاء

بنية الخطأ:

{ "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 فقط عندما تُجيب الواجهة البرمجية على الطلب مباشرة (قرارات المصادقة وحد المعدل والتخزين المؤقت) بدلًا من تمريره إلى المنصة.

الكود	HTTP	المعنى
unauthorized	401	رأس Authorization مفقود أو غير صالح
forbidden	403	موثَّق ولكن يفتقر إلى الصلاحية، أو إلى تسجيل في البرنامج التجريبي، أو إلى خطة Enterprise سارية (الواجهة البرمجية حصرية لخطة Enterprise)
not_found	404	المورد غير موجود أو لا ينتمي إلى متجرك
bad_request	400	خطأ في التحقق؛ راجع message
method_not_allowed	405	المسار موجود لكن لطريقة HTTP أخرى
rate_limited	429	تجاوز الحد لكل دقيقة؛ يُرفق رأس Retry-After
too_many_concurrent	429	عدد كبير من النداءات المكلفة قيد التنفيذ (الصور، توليد الذكاء الاصطناعي)؛ أعد المحاولة بعد ثوانٍ
quota_exceeded	402	تم بلوغ الحد الشهري؛ ارقَ إلى خطة أعلى أو انتظر
server_error	500	خطأ غير متوقع في الخادم؛ آمن لإعادة المحاولة على النداءات الـ idempotent

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

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

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

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