# PlayDrop MCP のアップロードエラーと復旧方法

PlayDrop の MCP ツールが返すエラーの形式、同じ requestId で再試行すべきとき、よくあるエラーコードごとの直し方を説明します。

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

PlayDrop の MCP ツールのエラーはすべて、変わらない `error` コードと、`path`、`field`、`name`、`expected` などの詳細を保持したうえで、次の情報を追加します。

- `message`：何が起きたかをわかりやすく説明します。
- `retryable`：まったく同じ呼び出しがあとで成功しうる場合にだけ `true` になります。
- `nextAction`：具体的な修正方法です。
- `docsUrl` と `documentationTopic`：読むべきガイドです。`get_documentation` でも読めます。

## 再試行するか、修正するか

- **再試行できるエラー**（一時的な障害、レート制限、中断された完了処理）：少し待ってから、同じ `requestId` でまったく同じ呼び出しを再試行します。別のバージョンは作らないでください。
- **レスポンスが失われた場合**：成功したかどうかわからないので、同じ `requestId` で同じ内容を再試行します。PlayDrop は二重に公開せず、最初の結果を返します。
- **入力が拒否された場合**：まず、示されたフィールドやファイルを修正します。内容を変えたら新しい `requestId` が必要です。入力を変えずに再試行しても、また失敗します。
- **パッケージの一部だけが完了した場合**：完了した項目は公開されたまま残ります。修正したリクエストには、終わっていない作業だけを含めてください。
- **`send_feedback`** には再試行用のキーがありません。成否がはっきりしない失敗のあとは、自動で再送しないでください。最初のメッセージが届いている可能性があります。

## よくあるエラー

| コード | 対処法 |
|---|---|
| `advanced_upload_required` | ゲームが SDK、サーバー、別ファイル、パッケージ専用のフィールドを使っています。それらの機能は残したまま、新しい `requestId` で[パッケージ](https://www.playdrop.ai/ja/create/learn/packaging)をアップロードしてください。 |
| `invalid_html_file` | HTML が空か、10 MiB を超えています。大きなゲームにはパッケージを使ってください。 |
| `visibility_required` | パッケージのアプリに公開範囲がありません。リクエストかアプリに `visibility` を設定してください：`public`、`unlisted`、`private`。 |
| `invalid_visibility` | `public`、`unlisted`、`private` のいずれかを使ってください。 |
| `visibility_conflict` | リクエストとアプリのエントリーで、異なる公開範囲が指定されています。公開範囲が知らないうちに変わらないよう、1つだけ指定してください。 |
| `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` はすでに別の内容に使われています。新しい ID を使うか、元の内容を変えずに再送してください。 |
| `catalogue_file_missing_or_invalid` | アップロードされていないファイルがあるか、ファイルのバイトが一致しません。同じ入力と同じ `requestId` でもう一度 `prepare_catalogue_upload` を呼び出し、不足しているファイルを 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 を超える場合：展開して、署名付きファイルでフォルダーをアップロードしてください。1ファイルあたり最大 50 MiB まで使えます。展開後に 200 MiB を超える場合：ゲーム自体が1つのバージョンには大きすぎます。アセットを圧縮するか削除してください。 |
| `procedural_module_validation_unavailable` | 実行可能なプロシージャル 3D や独自形式のモデルは、MCP ではアップロードできません。ベイクするか、公開済みのアセットを参照してください。 |
| `upload_expired`, `upload_cancelled` | 新しい `requestId` でアップロードを準備し直し、30分以内に完了してください。 |
| `invalid_token`, `insufficient_scope` | AI アプリで PlayDrop アカウントを接続し直し、公開を許可してください。 |

無効なタグ、コントローラーの宣言、プレイモードなど、カタログのフィールドのエラーについては、[catalogue.json リファレンス](https://www.playdrop.ai/ja/create/learn/catalogue-json)をご覧ください。

## 接続と添付ファイル

- **接続の期限切れ**：使用中の接続は自動で更新されます。30日間使われていない接続や、このルールができる前に期限が切れた接続は、もう一度接続する必要があります。
- **添付ファイルの拒否**：PlayDrop がファイルをダウンロードするのは、ホスト自身の添付ファイルサービスからだけです。これはファイルホストに関する制限で、国による制限ではありません。ホストが解決した添付ファイルを渡すか、署名付き URL でファイルをアップロードしてください。`download_url` や `file_id` を勝手に作るのは絶対にやめてください。

## 問題を報告する

エラーが間違っているように見える場合や、示された次の操作がうまくいかない場合は、ツール名、エラーコード、送信した内容（トークンや署名付き URL を除く）、期待した結果を添えて、`send_feedback` を1回だけ呼び出してください。

## 関連ガイド

- [AI アプリから公開する](https://www.playdrop.ai/ja/create/learn/mcp-publishing): AI エージェントが MCP で PlayDrop に公開する方法：シンプルな方法とパッケージの方法、非公開テスト、publish_game_version、更新、制限、復旧。
- [パッケージ化と .play](https://www.playdrop.ai/ja/create/learn/packaging): ルートに catalogue.json を置いたビルド済みのフォルダー、ZIP、.play を用意し、掲載メディアとサーバーを宣言して、prepare_catalogue_upload でアップロードします。
- [トラブルシューティング](https://www.playdrop.ai/ja/create/learn/troubleshooting): 制作タスクを開始できない場合、伝わりにくい依頼文、報酬や収益が見つからない場合、クレジットの上限、ウェブゲームのインポートの問題を解決します。