Tài liệu tham khảo

Lỗi tải lên qua MCP của PlayDrop và cách khôi phục

Cấu trúc lỗi mà các công cụ MCP của PlayDrop trả về, khi nào thử lại với cùng requestId, và cách khắc phục từng mã lỗi thường gặp.

Mỗi lỗi từ công cụ MCP của PlayDrop đều giữ mã error ổn định cùng mọi chi tiết như path, field, name hoặc expected, và thêm:

message: điều gì đã sai, bằng lời dễ hiểu.
retryable: chỉ là true khi chính lệnh gọi y hệt đó có thể thành công về sau.
nextAction: cách sửa cụ thể.
docsUrl và documentationTopic: hướng dẫn cần đọc, cũng có sẵn qua get_documentation.

Thử lại hay sửa

Lỗi có thể thử lại (lỗi tạm thời, giới hạn tần suất, bước hoàn tất bị gián đoạn): sau một lúc ngắn, hãy thử lại chính lệnh gọi đó với cùng requestId. Đừng tạo thêm phiên bản khác.
Mất phản hồi: bạn không biết lệnh gọi có thành công hay không, nên hãy thử lại với nội dung y hệt và cùng requestId. PlayDrop trả về kết quả ban đầu thay vì xuất bản hai lần.
Dữ liệu bị từ chối: hãy sửa trường hoặc tệp được nêu tên trước. Nội dung đã thay đổi cần một requestId mới; thử lại với dữ liệu không đổi sẽ lại thất bại.
Kết quả gói chỉ hoàn tất một phần: các mục đã hoàn tất vẫn được xuất bản. Yêu cầu đã sửa chỉ nên chứa phần việc chưa xong.
send_feedback không có khóa thử lại. Sau một lỗi không rõ ràng, đừng tự động gửi lại: tin nhắn đầu tiên có thể đã đến nơi.

Lỗi thường gặp

Mã	Cần làm gì
`advanced_upload_required`	Game dùng SDK, máy chủ, các tệp riêng hoặc trường chỉ dành cho gói. Hãy giữ các tính năng đó và tải lên một gói với `requestId` mới.
`invalid_html_file`	HTML trống hoặc lớn hơn 10 MiB. Hãy dùng gói cho game lớn hơn.
`visibility_required`	Một ứng dụng trong gói chưa có chế độ hiển thị. Đặt `visibility` trên yêu cầu hoặc trên ứng dụng: `public`, `unlisted` hoặc `private`.
`invalid_visibility`	Hãy dùng `public`, `unlisted` hoặc `private`.
`visibility_conflict`	Yêu cầu và một mục ứng dụng đòi các chế độ hiển thị khác nhau. Hãy chỉ đưa một giá trị, để nhóm người xem không bao giờ bị thay đổi một cách âm thầm.
`expected_current_version_required`	Thêm tên của mọi ứng dụng vào `expectedCurrentVersion`: `null` cho game mới, nếu không thì là phiên bản hiện tại từ `list_games`.
`current_version_changed`	Có người đã xuất bản một phiên bản mới hơn. Hãy gọi `list_games`, xác nhận mục tiêu với người dùng của bạn, rồi tải lên với phiên bản hiện tại và một `requestId` mới.
`game_exists_use_id`, `game_not_found`	Gọi `list_games`, dùng đúng `gameId` hoặc tên, và giữ nguyên tên hiện có của game.
`request_id_content_conflict`	`requestId` này đã thuộc về một nội dung khác. Hãy dùng ID mới, hoặc gửi lại nội dung ban đầu mà không thay đổi.
`catalogue_file_missing_or_invalid`	Một tệp chưa được tải lên hoặc các byte của nó không khớp. Gọi lại `prepare_catalogue_upload` với dữ liệu y hệt và cùng `requestId`, PUT các tệp còn thiếu, rồi hoàn tất lại.
`catalogue_files_unclaimed`	Một số tệp không được mục catalogue nào dùng. Hãy tham chiếu chúng, gán `role: "LISTING"` và `app` cho tệp giới thiệu, hoặc xóa chúng.
`entry_point_missing`	`apps[].file` nêu tên một tệp chưa được tải lên. Nếu không có `file`, mục này mặc định là `<name>.html`.
`archive_catalogue_required`	Đặt catalogue.json ở thư mục gốc của tệp ZIP, không phải bên trong một thư mục.
`archive_too_large`	Trên 20 MiB khi nén: hãy giải nén và tải thư mục lên bằng tệp có chữ ký, cho phép tối đa 50 MiB mỗi tệp. Trên 200 MiB khi giải nén: bản thân game quá lớn cho một phiên bản; hãy nén hoặc bớt tài nguyên.
`procedural_module_validation_unavailable`	Không thể tải mô hình 3D procedural hoặc mô hình định dạng tùy chỉnh thực thi được lên qua MCP. Hãy bake chúng hoặc tham chiếu một tài nguyên đã xuất bản.
`upload_expired`, `upload_cancelled`	Chuẩn bị lại lần tải lên với một `requestId` mới và hoàn tất trong vòng 30 phút.
`invalid_token`, `insufficient_scope`	Kết nối lại tài khoản PlayDrop trong ứng dụng AI của bạn và cho phép xuất bản.

Các lỗi trường catalogue như thẻ, khai báo tay cầm hoặc chế độ người chơi không hợp lệ sẽ trỏ đến tài liệu tham khảo catalogue.json.

Kết nối và tệp đính kèm

Kết nối hết hạn: một kết nối đang hoạt động tự gia hạn khi được dùng. Một kết nối không dùng trong 30 ngày, hoặc đã hết hạn trước khi có quy tắc này, cần được kết nối lại.
Tệp đính kèm bị từ chối: PlayDrop chỉ tải tệp từ dịch vụ đính kèm của chính host. Đây là giới hạn về nơi lưu tệp, không phải giới hạn theo quốc gia. Hãy truyền tệp đính kèm do host phân giải, hoặc tải các tệp lên bằng URL có chữ ký. Không bao giờ tự bịa ra download_url hay file_id.

Báo cáo sự cố

Nếu một lỗi có vẻ sai hoặc hành động tiếp theo không hiệu quả, hãy gọi send_feedback một lần với tên công cụ, mã lỗi, những gì bạn đã gửi (không kèm token hay URL có chữ ký) và kết quả bạn mong đợi.

Thử lại hay sửa

Lỗi có thể thử lại (lỗi tạm thời, giới hạn tần suất, bước hoàn tất bị gián đoạn): sau một lúc ngắn, hãy thử lại chính lệnh gọi đó với cùng requestId. Đừng tạo thêm phiên bản khác.
Mất phản hồi: bạn không biết lệnh gọi có thành công hay không, nên hãy thử lại với nội dung y hệt và cùng requestId. PlayDrop trả về kết quả ban đầu thay vì xuất bản hai lần.
Dữ liệu bị từ chối: hãy sửa trường hoặc tệp được nêu tên trước. Nội dung đã thay đổi cần một requestId mới; thử lại với dữ liệu không đổi sẽ lại thất bại.
Kết quả gói chỉ hoàn tất một phần: các mục đã hoàn tất vẫn được xuất bản. Yêu cầu đã sửa chỉ nên chứa phần việc chưa xong.
send_feedback không có khóa thử lại. Sau một lỗi không rõ ràng, đừng tự động gửi lại: tin nhắn đầu tiên có thể đã đến nơi.

Lỗi thường gặp

Mã	Cần làm gì
`advanced_upload_required`	Game dùng SDK, máy chủ, các tệp riêng hoặc trường chỉ dành cho gói. Hãy giữ các tính năng đó và tải lên một gói với `requestId` mới.
`invalid_html_file`	HTML trống hoặc lớn hơn 10 MiB. Hãy dùng gói cho game lớn hơn.
`visibility_required`	Một ứng dụng trong gói chưa có chế độ hiển thị. Đặt `visibility` trên yêu cầu hoặc trên ứng dụng: `public`, `unlisted` hoặc `private`.
`invalid_visibility`	Hãy dùng `public`, `unlisted` hoặc `private`.
`visibility_conflict`	Yêu cầu và một mục ứng dụng đòi các chế độ hiển thị khác nhau. Hãy chỉ đưa một giá trị, để nhóm người xem không bao giờ bị thay đổi một cách âm thầm.
`expected_current_version_required`	Thêm tên của mọi ứng dụng vào `expectedCurrentVersion`: `null` cho game mới, nếu không thì là phiên bản hiện tại từ `list_games`.
`current_version_changed`	Có người đã xuất bản một phiên bản mới hơn. Hãy gọi `list_games`, xác nhận mục tiêu với người dùng của bạn, rồi tải lên với phiên bản hiện tại và một `requestId` mới.
`game_exists_use_id`, `game_not_found`	Gọi `list_games`, dùng đúng `gameId` hoặc tên, và giữ nguyên tên hiện có của game.
`request_id_content_conflict`	`requestId` này đã thuộc về một nội dung khác. Hãy dùng ID mới, hoặc gửi lại nội dung ban đầu mà không thay đổi.
`catalogue_file_missing_or_invalid`	Một tệp chưa được tải lên hoặc các byte của nó không khớp. Gọi lại `prepare_catalogue_upload` với dữ liệu y hệt và cùng `requestId`, PUT các tệp còn thiếu, rồi hoàn tất lại.
`catalogue_files_unclaimed`	Một số tệp không được mục catalogue nào dùng. Hãy tham chiếu chúng, gán `role: "LISTING"` và `app` cho tệp giới thiệu, hoặc xóa chúng.
`entry_point_missing`	`apps[].file` nêu tên một tệp chưa được tải lên. Nếu không có `file`, mục này mặc định là `<name>.html`.
`archive_catalogue_required`	Đặt catalogue.json ở thư mục gốc của tệp ZIP, không phải bên trong một thư mục.
`archive_too_large`	Trên 20 MiB khi nén: hãy giải nén và tải thư mục lên bằng tệp có chữ ký, cho phép tối đa 50 MiB mỗi tệp. Trên 200 MiB khi giải nén: bản thân game quá lớn cho một phiên bản; hãy nén hoặc bớt tài nguyên.
`procedural_module_validation_unavailable`	Không thể tải mô hình 3D procedural hoặc mô hình định dạng tùy chỉnh thực thi được lên qua MCP. Hãy bake chúng hoặc tham chiếu một tài nguyên đã xuất bản.
`upload_expired`, `upload_cancelled`	Chuẩn bị lại lần tải lên với một `requestId` mới và hoàn tất trong vòng 30 phút.
`invalid_token`, `insufficient_scope`	Kết nối lại tài khoản PlayDrop trong ứng dụng AI của bạn và cho phép xuất bản.

Các lỗi trường catalogue như thẻ, khai báo tay cầm hoặc chế độ người chơi không hợp lệ sẽ trỏ đến tài liệu tham khảo catalogue.json.

Kết nối và tệp đính kèm

Kết nối hết hạn: một kết nối đang hoạt động tự gia hạn khi được dùng. Một kết nối không dùng trong 30 ngày, hoặc đã hết hạn trước khi có quy tắc này, cần được kết nối lại.
Tệp đính kèm bị từ chối: PlayDrop chỉ tải tệp từ dịch vụ đính kèm của chính host. Đây là giới hạn về nơi lưu tệp, không phải giới hạn theo quốc gia. Hãy truyền tệp đính kèm do host phân giải, hoặc tải các tệp lên bằng URL có chữ ký. Không bao giờ tự bịa ra download_url hay file_id.