참조

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 앱에서 PlayDrop 계정을 다시 연결하고 게시를 허용하세요.

잘못된 태그, 컨트롤러 선언, 플레이어 모드 같은 카탈로그 필드 오류는 catalogue.json 참조를 안내합니다.

연결과 첨부 파일

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

문제 신고하기

오류가 잘못된 것 같거나 안내된 다음 작업이 통하지 않으면, 도구 이름, 오류 코드, 보낸 내용(토큰이나 서명된 URL 제외), 기대한 결과를 담아 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 앱에서 PlayDrop 계정을 다시 연결하고 게시를 허용하세요.

잘못된 태그, 컨트롤러 선언, 플레이어 모드 같은 카탈로그 필드 오류는 catalogue.json 참조를 안내합니다.

연결과 첨부 파일

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