بنية الخطأ:

{ "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 دائمًا عند التواصل مع الدعم.

المقالات ذات الصلة

الأخطاء

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