# PlayDrop MCP 上傳錯誤與復原方式

PlayDrop MCP 工具傳回的錯誤格式、何時以相同的 requestId 重試，以及各種常見錯誤代碼的修正方式。

Source: https://www.playdrop.ai/zh-hant/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/zh-hant/create/learn/packaging)。 |
| `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` 已屬於不同的內容。請使用新的 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：請解壓縮，並以簽名檔案上傳資料夾，每個檔案最多可達 50 MiB。解壓縮後超過 200 MiB：遊戲本身對單一版本來說太大；請壓縮或移除素材。 |
| `procedural_module_validation_unavailable` | 可執行的程序化 3D 或自訂格式模型無法透過 MCP 上傳。請將它們烘焙，或參照已發布的素材。 |
| `upload_expired`、`upload_cancelled` | 以新的 `requestId` 重新準備上傳，並在 30 分鐘內完成。 |
| `invalid_token`、`insufficient_scope` | 在你的 AI App 中重新連接 PlayDrop 帳號，並允許發布。 |

目錄欄位錯誤（例如無效的標籤、控制器宣告或玩家模式）會指向 [catalogue.json 參考](https://www.playdrop.ai/zh-hant/create/learn/catalogue-json)。

## 連線與附件

- **連線過期**：使用中的連線會自動續期。超過 30 天未使用的連線，或在此規則生效前就已過期的連線，需要重新連接。
- **附件遭拒**：PlayDrop 只會從主機端自己的附件服務下載檔案。這是檔案來源的限制，不是國家或地區的限制。請傳入主機端解析的附件，或以簽名網址上傳檔案。絕不要自行編造 `download_url` 或 `file_id`。

## 回報問題

如果錯誤看起來不對，或建議的下一步無效，請呼叫 `send_feedback` 一次，附上工具名稱、錯誤代碼、你傳送的內容（不含權杖或簽名網址）以及你預期的結果。

## 相關指南

- [從你的 AI App 發布](https://www.playdrop.ai/zh-hant/create/learn/mcp-publishing): AI 代理如何透過 MCP 發布到 PlayDrop：簡易方式與套件方式、私人測試、publish_game_version、更新、限制與復原。
- [打包與 .play](https://www.playdrop.ai/zh-hant/create/learn/packaging): 安排根目錄含 catalogue.json 的建置遊戲資料夾、ZIP 或 .play，宣告上架媒體與伺服器，並用 prepare_catalogue_upload 上傳。
- [疑難排解](https://www.playdrop.ai/zh-hant/create/learn/troubleshooting): 處理無法開始的製作工作、不清楚的請求、未出現的獎勵或收益、點數上限與網頁遊戲匯入問題。