# أخطاء الرفع عبر MCP في PlayDrop وطريقة الاستعادة منها

شكل الأخطاء التي تعيدها أدوات MCP في PlayDrop، ومتى تعيد المحاولة بـ requestId نفسه، وطريقة إصلاح كل رمز خطأ شائع.

Source: https://www.playdrop.ai/ar/create/learn/errors

يحتفظ كل خطأ من أدوات MCP في PlayDrop برمز `error` الثابت الخاص به وبأي تفاصيل مثل `path` أو `field` أو `name` أو `expected`، ويضيف:

- `message`: ما الذي حدث، بكلمات بسيطة.
- `retryable`: `true` فقط عندما يمكن أن ينجح الاستدعاء المطابق لاحقًا.
- `nextAction`: التصحيح المحدد المطلوب.
- `docsUrl` و`documentationTopic`: الدليل الذي يجب قراءته، والمتاح أيضًا عبر `get_documentation`.

## أعد المحاولة أو صحّح

- **الأخطاء القابلة لإعادة المحاولة** (الأعطال المؤقتة، وحدود المعدل، والإكمال المنقطع): أعد الاستدعاء المطابق بـ `requestId` نفسه بعد انتظار قصير. لا تنشئ إصدارًا آخر.
- **ضياع الرد:** لا يمكنك معرفة هل نجح الاستدعاء، لذا أعد إرسال المحتوى المطابق بـ `requestId` نفسه. يعيد PlayDrop النتيجة الأصلية بدل النشر مرتين.
- **رفض المدخلات:** أصلح الحقل أو الملف المذكور أولًا. يحتاج المحتوى المتغير إلى `requestId` جديد؛ وإعادة المحاولة بمدخلات لم تتغير تفشل مجددًا.
- **نتائج الحزمة الجزئية:** تبقى العناصر المكتملة منشورة. يجب أن يحتوي الطلب المصحح على العمل غير المكتمل فقط.
- **`send_feedback`** ليس له مفتاح إعادة محاولة. بعد فشل غامض لا تعد الإرسال تلقائيًا: فقد تكون الرسالة الأولى قد وصلت.

## الأخطاء الشائعة

| الرمز | ماذا تفعل |
|---|---|
| `advanced_upload_required` | تستخدم اللعبة SDK أو خادمًا أو ملفات منفصلة أو حقولًا خاصة بالحزم. احتفظ بتلك الميزات وارفع [حزمة](https://www.playdrop.ai/ar/create/learn/packaging) بـ `requestId` جديد. |
| `invalid_html_file` | ملف HTML فارغ أو أكبر من 10 MiB. استخدم حزمة للألعاب الأكبر. |
| `visibility_required` | تطبيق في الحزمة بلا قيمة ظهور. عيّن `visibility` في الطلب أو في التطبيق: `public` أو `unlisted` أو `private`. |
| `invalid_visibility` | استخدم `public` أو `unlisted` أو `private`. |
| `visibility_conflict` | يطلب الطلب ومدخل تطبيق ظهورين مختلفين. حدّد قيمة واحدة، حتى لا يتغير الجمهور بصمت أبدًا. |
| `expected_current_version_required` | أضف اسم كل تطبيق إلى `expectedCurrentVersion`: `null` للعبة جديدة، وإلا فالإصدار الحالي من `list_games`. |
| `current_version_changed` | نشر شخص ما إصدارًا أحدث. استدعِ `list_games`، وأكّد الهدف مع الشخص الذي تعمل معه، ثم ارفع بالإصدار الحالي و`requestId` جديد. |
| `game_exists_use_id`، `game_not_found` | استدعِ `list_games`، واستخدم `gameId` أو الاسم الصحيح، واحتفظ بالاسم الحالي للعبة. |
| `request_id_content_conflict` | هذا `requestId` ينتمي بالفعل إلى محتوى مختلف. استخدم معرّفًا جديدًا، أو أعد إرسال المحتوى الأصلي دون تغيير. |
| `catalogue_file_missing_or_invalid` | لم يُرفع ملف ما أو أن بايتاته لا تتطابق. استدعِ `prepare_catalogue_upload` مجددًا بالمدخلات نفسها و`requestId` نفسه، وارفع الملفات الناقصة بطلب PUT، ثم أكمل الرفع مجددًا. |
| `catalogue_files_unclaimed` | بعض الملفات لا يستخدمها أي مدخل في الكتالوج. أشر إليها، أو أعطِ ملفات صفحة اللعبة `role: "LISTING"` و`app`، أو احذفها. |
| `entry_point_missing` | يسمّي `apps[].file` ملفًا لم يُرفع. ودون `file`، تكون صفحة الدخول الافتراضية `<name>.html`. |
| `archive_catalogue_required` | ضع catalogue.json في جذر ملف ZIP، لا داخل مجلد. |
| `archive_too_large` | أكثر من 20 MiB مضغوطًا: فك ضغطه وارفع ملفات المجلد عبر روابط موقّعة، ما يسمح بما يصل إلى 50 MiB لكل ملف. أكثر من 200 MiB بعد فك الضغط: اللعبة نفسها أكبر من أن تُرفع في إصدار واحد؛ اضغط الأصول أو احذف بعضها. |
| `procedural_module_validation_unavailable` | لا يمكن رفع النماذج الإجرائية ثلاثية الأبعاد القابلة للتنفيذ أو نماذج الصيغ المخصصة عبر MCP. حوّلها مسبقًا إلى صيغة ثابتة أو أشر إلى أصل منشور. |
| `upload_expired`، `upload_cancelled` | حضّر الرفع مجددًا بـ `requestId` جديد وأكمله خلال 30 دقيقة. |
| `invalid_token`، `insufficient_scope` | أعد ربط حساب PlayDrop في تطبيق الذكاء الاصطناعي واسمح بالنشر. |

تشير أخطاء حقول الكتالوج، مثل وسم غير صالح أو تصريح خاطئ بوحدات التحكم أو بطريقة اللعب، إلى [مرجع catalogue.json](https://www.playdrop.ai/ar/create/learn/catalogue-json).

## الاتصال والمرفقات

- **انتهاء صلاحية الاتصال:** يتجدد الاتصال النشط تلقائيًا ما دام مستخدمًا. أما الاتصال غير المستخدم منذ 30 يومًا، أو الذي انتهت صلاحيته قبل هذه القاعدة، فيحتاج إلى إعادة الربط.
- **رفض المرفق:** لا ينزّل PlayDrop الملفات إلا من خدمة المرفقات الخاصة بالمضيف. هذا قيد على مضيف الملفات، وليس قيدًا على البلد. مرّر المرفق كما يوفّره المضيف نفسه، أو ارفع الملفات بروابط موقّعة. لا تختلق أبدًا `download_url` أو `file_id`.

## أبلغ عن مشكلة

إذا بدا خطأ غير صحيح أو لم ينجح الإجراء التالي، فاستدعِ `send_feedback` مرة واحدة مع اسم الأداة ورمز الخطأ وما أرسلته (دون رموز الوصول أو الروابط الموقّعة) وما توقعته.

## أدلة ذات صلة

- [النشر من تطبيق الذكاء الاصطناعي](https://www.playdrop.ai/ar/create/learn/mcp-publishing): كيف ينشر وكلاء الذكاء الاصطناعي على PlayDrop عبر MCP: المسار البسيط ومسار الحزمة، والاختبار الخاص، وpublish_game_version، والتحديثات والحدود والاستعادة.
- [التحزيم و.play](https://www.playdrop.ai/ar/create/learn/packaging): نظّم مجلد لعبة مبنية أو ملف ZIP أو .play مع catalogue.json في جذره، وصرّح بوسائط صفحة اللعبة والخوادم، وارفعه باستخدام prepare_catalogue_upload.
- [حل المشكلات](https://www.playdrop.ai/ar/create/learn/troubleshooting): عالج العمليات المحجوبة والطلبات الغامضة والمكافآت أو الأرباح المفقودة وحدود الرصيد ومشكلات استيراد ألعاب الويب.