参考

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`	有些文件没有被任何 catalogue 条目使用。请引用它们，为商店页面文件设置 `role: "LISTING"` 和 `app`，或者删除它们。
`entry_point_missing`	`apps[].file` 指向一个没有上传的文件。没有 `file` 时，入口默认为 `<name>.html`。
`archive_catalogue_required`	把 catalogue.json 放在 ZIP 的根目录，而不是某个文件夹中。
`archive_too_large`	压缩后超过 20 MiB：请解压，并通过签名 URL 上传文件夹中的文件，这样每个文件最多可达 50 MiB。解压后超过 200 MiB：游戏本身对单个版本来说太大；请压缩或删除部分素材。
`procedural_module_validation_unavailable`	可执行的程序化 3D 模型或自定义格式模型不能通过 MCP 上传。请将其烘焙，或引用已发布的素材。
`upload_expired`、`upload_cancelled`	用新的 `requestId` 重新准备上传，并在 30 分钟内完成。
`invalid_token`、`insufficient_scope`	在你的 AI 应用中重新连接 PlayDrop 账号，并允许发布。

无效标签、控制器声明或玩家模式等 catalogue 字段错误，请参阅 catalogue.json 参考。

连接和附件

连接已过期：处于活跃状态的连接会在使用时自动续期。30 天未使用的连接，或在此规则生效前就已过期的连接，需要重新连接。
附件被拒绝：PlayDrop 只从宿主自己的附件服务下载文件。这是文件托管方的限制，不是国家或地区限制。请传入由宿主解析的附件，或使用签名 URL 上传文件。绝不能编造 download_url 或 file_id。

报告问题

如果某个错误看起来不对，或者给出的下一步操作无效，请调用一次 send_feedback，附上工具名称、错误代码、你发送的内容（不含令牌或签名 URL）以及你预期的结果。

重试还是修正

可重试的错误（临时故障、频率限制、完成步骤中断）：稍等片刻后，用同一个 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`	有些文件没有被任何 catalogue 条目使用。请引用它们，为商店页面文件设置 `role: "LISTING"` 和 `app`，或者删除它们。
`entry_point_missing`	`apps[].file` 指向一个没有上传的文件。没有 `file` 时，入口默认为 `<name>.html`。
`archive_catalogue_required`	把 catalogue.json 放在 ZIP 的根目录，而不是某个文件夹中。
`archive_too_large`	压缩后超过 20 MiB：请解压，并通过签名 URL 上传文件夹中的文件，这样每个文件最多可达 50 MiB。解压后超过 200 MiB：游戏本身对单个版本来说太大；请压缩或删除部分素材。
`procedural_module_validation_unavailable`	可执行的程序化 3D 模型或自定义格式模型不能通过 MCP 上传。请将其烘焙，或引用已发布的素材。
`upload_expired`、`upload_cancelled`	用新的 `requestId` 重新准备上传，并在 30 分钟内完成。
`invalid_token`、`insufficient_scope`	在你的 AI 应用中重新连接 PlayDrop 账号，并允许发布。

无效标签、控制器声明或玩家模式等 catalogue 字段错误，请参阅 catalogue.json 参考。

连接和附件

连接已过期：处于活跃状态的连接会在使用时自动续期。30 天未使用的连接，或在此规则生效前就已过期的连接，需要重新连接。
附件被拒绝：PlayDrop 只从宿主自己的附件服务下载文件。这是文件托管方的限制，不是国家或地区限制。请传入由宿主解析的附件，或使用签名 URL 上传文件。绝不能编造 download_url 或 file_id。