# PlayDrop MCP 上传错误及恢复方法

PlayDrop MCP 工具返回的错误结构、何时使用同一个 requestId 重试，以及每个常见错误代码的修复方法。

Source: https://www.playdrop.ai/zh-hans/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-hans/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` | 有些文件没有被任何 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 参考](https://www.playdrop.ai/zh-hans/create/learn/catalogue-json)。

## 连接和附件

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

## 报告问题

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

## 相关指南

- [从你的 AI 应用发布](https://www.playdrop.ai/zh-hans/create/learn/mcp-publishing): AI Agent 如何通过 MCP 发布到 PlayDrop：简单方式和包方式、私密测试、publish_game_version、更新、限制和恢复。
- [打包和 .play](https://www.playdrop.ai/zh-hans/create/learn/packaging): 整理一个根目录带有 catalogue.json 的已构建游戏文件夹、ZIP 或 .play，声明商店页面媒体和服务器，并用 prepare_catalogue_upload 上传。
- [问题排查](https://www.playdrop.ai/zh-hans/create/learn/troubleshooting): 处理受阻的制作任务、不明确的提示、未出现的奖励或收益、点数限制与网页游戏导入问题。