بنية الخطأ:
{ "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 | المعنى |
| 401 | رأس Authorization مفقود أو غير صالح |
| 403 | موثَّق ولكن يفتقر إلى الصلاحية، أو إلى تسجيل في البرنامج التجريبي، أو إلى خطة Enterprise سارية (الواجهة البرمجية حصرية لخطة Enterprise) |
| 404 | المورد غير موجود أو لا ينتمي إلى متجرك |
| 400 | خطأ في التحقق؛ راجع |
| 405 | المسار موجود لكن لطريقة HTTP أخرى |
| 429 | تجاوز الحد لكل دقيقة؛ يُرفق رأس |
| 429 | عدد كبير من النداءات المكلفة قيد التنفيذ (الصور، توليد الذكاء الاصطناعي)؛ أعد المحاولة بعد ثوانٍ |
| 402 | تم بلوغ الحد الشهري؛ ارقَ إلى خطة أعلى أو انتظر |
| 500 | خطأ غير متوقع في الخادم؛ آمن لإعادة المحاولة على النداءات الـ idempotent |
كائن details محجوز لإخراج تحقُّق مُهيكَل مستقبلًا. لا توجد نقطة نهاية تُصدره اليوم، فلا تبنِ منطقك عليه.
إعادة محاولة عملية كتابة فاشلة
على https://api.dzbuild.app، تُخزَّن استجابة 4xx الناتجة عن عملية كتابة مقابل Idempotency-Key الخاص بك لمدة 24 ساعة: إعادة المحاولة بالمفتاح نفسه تعيد الخطأ ذاته موسومًا بـIdempotency-Replay: 1، دون تنفيذ أي شيء من جديد. صحِّح الطلب وأرسله بمفتاح جديد. أما الأخطاء التي تُرجَع قبل معالجة الطلب — 401 و403 و429 أو Idempotency-Key غير صالح التنسيق — فلا تُخزَّن، وكذلك استجابات 5xx، لذا يمكن إعادة المحاولة بالمفتاح نفسه بأمان. انظر Idempotency.
أرفق meta.request_id دائمًا عند التواصل مع الدعم.