رُوجع 2026-11-10 · إصدار API 2026-11-09 · قراءة Markdown
الأخطاء وإعادة المحاولة والاستعادة
تستخدم أخطاء واجهة البرمجة { "error": { "code": "…", "message": "…", "requestId": "…" } }
مع أخطاء حقول اختيارية وأخطاء وجهات وتلميحات إعادة محاولة وتسليمات إجراءات.
احفظ requestId للدعم. لا تسجّل بيانات الاعتماد أو عناوين URL الموقّعة للتحميل أو
محتوى الطلب الحساس عند جمع التشخيصات.
| الاستجابة | الاستعادة |
|---|---|
401 unauthenticated | تحقق من مفتاح منتج غائب أو مشوَّه أو مُلغى |
403 forbidden_scope / account_not_allowed | راجع نطاقات المفتاح ووصول الوجهة |
402 account_limit، seat_limit، storage_limit | راجع استحقاق مساحة العمل واستخدام الموارد |
402 subscription_inactive / trial_expired | عالِج حالة الفوترة؛ احفظ المسودات والعمل المدرول |
409 revision_conflict | اقرأ الإصدار الحالي، وراجع التغييرات وأعد تطبيقها عمدًا |
409 idempotency_conflict | أُعيد استخدام المفتاح بجسم مختلف؛ طابق العملية الأصلية |
409 consent_required | اطلب من شخص مصرَّح له إكمال تسليم المراجعة المقدَّم |
409 too_late_to_cancel | افحص حالة التسليم الفعلية؛ لا تدَّعِ نجاح الإلغاء |
media_expired / media_deleting | أعد رفع الأصلية وحدّث المسودة |
422 validation_failed | صحّح الحقول المهيكلة أو مشكلات كل وجهة |
429 rate_limited | احترم Retry-After؛ قلّل التزامن واستخدم التراجع |
submission_unknown | طابق النتيجة الخارجية الموجودة قبل محاولة إرسال آخر |
إعادة محاولة التغييرات الآمنة
أنشئ مفتاح idempotency قبل أول عملية تغيير واحفظ طلبها الدقيق.
إذا فُقدت الاستجابة، فقد تكون العملية قد نجحت بالفعل. أعد تشغيل
الطلب نفسه بالمفتاح نفسه؛ ولا تنشئ مفتاحًا جديدًا لمجرد انتهاء مهلة
الشبكة. تعيد أدوات MCP للتغيير إظهار مفتاحها، بما في ذلك في
إخفاقات transport_outcome_unknown. لا يعيد المحوّل المحاولة تلقائيًا للعمليات.
حدود السرعة التقنية لمساحة العمل ليست أرصدة نشر. استخدم /usage لمعرفة
الخطة الحالية ومعلومات المعدل. تراجع مع الأخطاء العابرة فقط عندما يكون ذلك
مناسبًا؛ إعادة محاولة أخطاء التخويل أو التحقق أو الموافقة البشرية دون
تغيير سببها لا تجدي.
النجاح الجزئي والمراقبة
دفعة النشر/الجدولة المقبولة هي مجموعة تسليمات مستقلة. احفظ الإيصالات الناجحة والروابط الأصلية. استعد وجهة فاشلة عبر نقطة نهاية إعادة المحاولة الخاصة بها بدلًا من إنشاء الدفعة كاملة مرة أخرى. فضّل خطافات الويب الموقَّعة؛ وإذا استخدمت الاستقصاء، فاستخدم عددًا محدودًا من المحاولات مع تأخيرات متزايدة وأحِل العمل غير المحلول إلى شخص.