參考資料

PlayDrop MCP 上傳錯誤與復原方式

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

每個 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` 上傳套件。
`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 參考。

連線與附件

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

回報問題

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

重試或修正

可重試的錯誤（暫時性失敗、頻率限制、中斷的完成步驟）：稍候片刻，以相同的 requestId 重試完全相同的呼叫。不要建立另一個版本。
回應遺失：你無法判斷是否成功，因此請以相同的 requestId 重試完全相同的內容。PlayDrop 會傳回原本的結果，而不會發布兩次。
輸入遭拒：先修正錯誤指出的欄位或檔案。內容變更後需要新的 requestId；以未變更的輸入重試會再次失敗。
套件部分完成：已完成的項目會維持發布狀態。修正後的請求應只包含尚未完成的工作。
send_feedback 沒有重試鍵。發生無法確定結果的失敗後，不要自動重新傳送：第一則訊息可能已經送達。

常見錯誤

代碼	處理方式
`advanced_upload_required`	遊戲使用了 SDK、伺服器、獨立檔案或僅限套件的欄位。保留這些功能，並以新的 `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` 已屬於不同的內容。請使用新的 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 參考。

連線與附件

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