# PlayDrop MCP 업로드 오류와 복구 방법

PlayDrop MCP 도구가 반환하는 오류 형식, 같은 requestId로 다시 시도해야 할 때, 자주 나오는 오류 코드별 해결 방법을 알아보세요.

Source: https://www.playdrop.ai/ko/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/ko/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 앱에서 PlayDrop 계정을 다시 연결하고 게시를 허용하세요. |

잘못된 태그, 컨트롤러 선언, 플레이어 모드 같은 카탈로그 필드 오류는 [catalogue.json 참조](https://www.playdrop.ai/ko/create/learn/catalogue-json)를 안내합니다.

## 연결과 첨부 파일

- **만료된 연결:** 사용 중인 연결은 자동으로 갱신됩니다. 30일 동안 쓰지 않은 연결이나 이 규칙이 생기기 전에 만료된 연결은 다시 연결해야 합니다.
- **첨부 파일 거부:** PlayDrop은 호스트 자체 첨부 파일 서비스에서만 파일을 내려받습니다. 이것은 국가 제한이 아니라 파일 호스트 제한입니다. 호스트가 확인한 첨부 파일을 넘기거나, 서명된 URL로 파일을 업로드하세요. `download_url`이나 `file_id`를 절대 지어내지 마세요.

## 문제 신고하기

오류가 잘못된 것 같거나 안내된 다음 작업이 통하지 않으면, 도구 이름, 오류 코드, 보낸 내용(토큰이나 서명된 URL 제외), 기대한 결과를 담아 `send_feedback`을 한 번 호출하세요.

## 관련 가이드

- [AI 앱에서 게시하기](https://www.playdrop.ai/ko/create/learn/mcp-publishing): AI 에이전트가 MCP로 PlayDrop에 게시하는 방법: 간단한 방식과 패키지 방식, 비공개 테스트, publish_game_version, 업데이트, 제한, 복구.
- [패키징과 .play](https://www.playdrop.ai/ko/create/learn/packaging): catalogue.json을 루트에 둔 빌드 폴더, ZIP 또는 .play를 구성하고, 등록 정보 미디어와 서버를 선언한 뒤 prepare_catalogue_upload로 업로드하세요.
- [문제 해결](https://www.playdrop.ai/ko/create/learn/troubleshooting): 막힌 제작 작업, 불명확한 요청, 누락된 보상이나 수익, 크레딧 한도, 웹 게임 가져오기 문제를 해결하세요.