Dokumentacja techniczna

Błędy przesyłania przez MCP PlayDrop i jak je naprawić

Struktura błędów zwracanych przez narzędzia MCP PlayDrop, kiedy ponawiać z tym samym requestId i jak naprawić każdy częsty kod błędu.

Każdy błąd narzędzia MCP PlayDrop zachowuje swój stały kod error i szczegóły, takie jak path, field, name lub expected, oraz dodaje:

message: co poszło nie tak, prostymi słowami.
retryable: true tylko wtedy, gdy identyczne wywołanie może się później udać.
nextAction: konkretna poprawka.
docsUrl i documentationTopic: poradnik do przeczytania, dostępny też przez get_documentation.

Ponów lub popraw

Błędy z możliwością ponowienia (chwilowe awarie, limity żądań, przerwane dokończenie przesłania): po krótkiej przerwie ponów identyczne wywołanie z tym samym requestId. Nie twórz kolejnej wersji.
Utracona odpowiedź: nie wiesz, czy się udało, więc ponów identyczną treść z tym samym requestId. PlayDrop zwróci pierwotny wynik zamiast publikować dwa razy.
Odrzucone dane wejściowe: najpierw popraw wskazane pole lub plik. Zmieniona treść wymaga nowego requestId; ponowienie niezmienionych danych znowu się nie powiedzie.
Częściowe wyniki pakietu: ukończone elementy pozostają opublikowane. Poprawione żądanie powinno zawierać tylko niedokończoną pracę.
send_feedback nie ma klucza ponowienia. Po niejednoznacznym błędzie nie wysyłaj automatycznie ponownie: pierwsza wiadomość mogła dotrzeć.

Częste błędy

Kod	Co zrobić
`advanced_upload_required`	Gra używa SDK, serwera, osobnych plików lub pól dostępnych tylko w pakietach. Zachowaj te funkcje i prześlij pakiet z nowym `requestId`.
`invalid_html_file`	HTML jest pusty lub większy niż 10 MiB. W większych grach użyj pakietu.
`visibility_required`	Aplikacja w pakiecie nie ma widoczności. Ustaw `visibility` w żądaniu lub w aplikacji: `public`, `unlisted` lub `private`.
`invalid_visibility`	Użyj `public`, `unlisted` lub `private`.
`visibility_conflict`	Żądanie i wpis aplikacji wskazują różne widoczności. Podaj jedną, aby odbiorcy nigdy nie zmienili się po cichu.
`expected_current_version_required`	Dodaj nazwę każdej aplikacji do `expectedCurrentVersion`: `null` dla nowej gry, a w przeciwnym razie bieżącą wersję z `list_games`.
`current_version_changed`	Ktoś opublikował nowszą wersję. Wywołaj `list_games`, potwierdź cel ze swoim użytkownikiem, a potem prześlij grę z bieżącą wersją i nowym `requestId`.
`game_exists_use_id`, `game_not_found`	Wywołaj `list_games`, użyj właściwego `gameId` lub nazwy i zachowaj dotychczasową nazwę gry.
`request_id_content_conflict`	Ten `requestId` należy już do innej treści. Użyj nowego ID albo wyślij ponownie oryginalną treść bez zmian.
`catalogue_file_missing_or_invalid`	Plik nie został przesłany albo jego bajty się nie zgadzają. Wywołaj ponownie `prepare_catalogue_upload` z identycznymi danymi i tym samym `requestId`, wyślij brakujące pliki przez PUT, a potem ponownie dokończ przesyłanie.
`catalogue_files_unclaimed`	Niektóre pliki nie są używane przez żaden wpis katalogu. Odwołaj się do nich, nadaj plikom strony gry `role: "LISTING"` i `app` albo je usuń.
`entry_point_missing`	`apps[].file` wskazuje plik, który nie został przesłany. Bez `file` wpis domyślnie przyjmuje `<name>.html`.
`archive_catalogue_required`	Umieść catalogue.json w katalogu głównym archiwum ZIP, a nie w folderze.
`archive_too_large`	Ponad 20 MiB po kompresji: rozpakuj archiwum i prześlij folder przez podpisane adresy URL, co pozwala na pliki do 50 MiB każdy. Ponad 200 MiB po rozpakowaniu: sama gra jest za duża na jedną wersję; skompresuj lub usuń zasoby.
`procedural_module_validation_unavailable`	Wykonywalnych proceduralnych modeli 3D ani modeli we własnych formatach nie można przesłać przez MCP. Wypal je albo odwołaj się do opublikowanego zasobu.
`upload_expired`, `upload_cancelled`	Przygotuj przesłanie ponownie z nowym `requestId` i dokończ je w ciągu 30 minut.
`invalid_token`, `insufficient_scope`	Połącz ponownie konto PlayDrop w aplikacji AI i zezwól na publikowanie.

Błędy pól katalogu, takie jak nieprawidłowy tag, deklaracja kontrolera lub tryb graczy, odsyłają do dokumentacji catalogue.json.

Połączenie i załączniki

Wygasłe połączenie: aktywne połączenie odnawia się samo, gdy jest używane. Połączenie nieużywane przez 30 dni albo takie, które wygasło przed wprowadzeniem tej zasady, trzeba nawiązać ponownie.
Odrzucony załącznik: PlayDrop pobiera pliki tylko z usługi załączników samego hosta. To ograniczenie hostingu plików, a nie ograniczenie dotyczące kraju. Przekaż załącznik rozwiązany przez hosta albo prześlij pliki przez podpisane adresy URL. Nigdy nie wymyślaj download_url ani file_id.

Zgłoś problem

Jeśli błąd wygląda na niewłaściwy albo następna akcja nie działa, wywołaj raz send_feedback z nazwą narzędzia, kodem błędu, tym, co wysłano (bez tokenów i podpisanych adresów URL), oraz tym, czego oczekiwano.

Ponów lub popraw

Błędy z możliwością ponowienia (chwilowe awarie, limity żądań, przerwane dokończenie przesłania): po krótkiej przerwie ponów identyczne wywołanie z tym samym requestId. Nie twórz kolejnej wersji.
Utracona odpowiedź: nie wiesz, czy się udało, więc ponów identyczną treść z tym samym requestId. PlayDrop zwróci pierwotny wynik zamiast publikować dwa razy.
Odrzucone dane wejściowe: najpierw popraw wskazane pole lub plik. Zmieniona treść wymaga nowego requestId; ponowienie niezmienionych danych znowu się nie powiedzie.
Częściowe wyniki pakietu: ukończone elementy pozostają opublikowane. Poprawione żądanie powinno zawierać tylko niedokończoną pracę.
send_feedback nie ma klucza ponowienia. Po niejednoznacznym błędzie nie wysyłaj automatycznie ponownie: pierwsza wiadomość mogła dotrzeć.

Częste błędy

Kod	Co zrobić
`advanced_upload_required`	Gra używa SDK, serwera, osobnych plików lub pól dostępnych tylko w pakietach. Zachowaj te funkcje i prześlij pakiet z nowym `requestId`.
`invalid_html_file`	HTML jest pusty lub większy niż 10 MiB. W większych grach użyj pakietu.
`visibility_required`	Aplikacja w pakiecie nie ma widoczności. Ustaw `visibility` w żądaniu lub w aplikacji: `public`, `unlisted` lub `private`.
`invalid_visibility`	Użyj `public`, `unlisted` lub `private`.
`visibility_conflict`	Żądanie i wpis aplikacji wskazują różne widoczności. Podaj jedną, aby odbiorcy nigdy nie zmienili się po cichu.
`expected_current_version_required`	Dodaj nazwę każdej aplikacji do `expectedCurrentVersion`: `null` dla nowej gry, a w przeciwnym razie bieżącą wersję z `list_games`.
`current_version_changed`	Ktoś opublikował nowszą wersję. Wywołaj `list_games`, potwierdź cel ze swoim użytkownikiem, a potem prześlij grę z bieżącą wersją i nowym `requestId`.
`game_exists_use_id`, `game_not_found`	Wywołaj `list_games`, użyj właściwego `gameId` lub nazwy i zachowaj dotychczasową nazwę gry.
`request_id_content_conflict`	Ten `requestId` należy już do innej treści. Użyj nowego ID albo wyślij ponownie oryginalną treść bez zmian.
`catalogue_file_missing_or_invalid`	Plik nie został przesłany albo jego bajty się nie zgadzają. Wywołaj ponownie `prepare_catalogue_upload` z identycznymi danymi i tym samym `requestId`, wyślij brakujące pliki przez PUT, a potem ponownie dokończ przesyłanie.
`catalogue_files_unclaimed`	Niektóre pliki nie są używane przez żaden wpis katalogu. Odwołaj się do nich, nadaj plikom strony gry `role: "LISTING"` i `app` albo je usuń.
`entry_point_missing`	`apps[].file` wskazuje plik, który nie został przesłany. Bez `file` wpis domyślnie przyjmuje `<name>.html`.
`archive_catalogue_required`	Umieść catalogue.json w katalogu głównym archiwum ZIP, a nie w folderze.
`archive_too_large`	Ponad 20 MiB po kompresji: rozpakuj archiwum i prześlij folder przez podpisane adresy URL, co pozwala na pliki do 50 MiB każdy. Ponad 200 MiB po rozpakowaniu: sama gra jest za duża na jedną wersję; skompresuj lub usuń zasoby.
`procedural_module_validation_unavailable`	Wykonywalnych proceduralnych modeli 3D ani modeli we własnych formatach nie można przesłać przez MCP. Wypal je albo odwołaj się do opublikowanego zasobu.
`upload_expired`, `upload_cancelled`	Przygotuj przesłanie ponownie z nowym `requestId` i dokończ je w ciągu 30 minut.
`invalid_token`, `insufficient_scope`	Połącz ponownie konto PlayDrop w aplikacji AI i zezwól na publikowanie.

Błędy pól katalogu, takie jak nieprawidłowy tag, deklaracja kontrolera lub tryb graczy, odsyłają do dokumentacji catalogue.json.

Połączenie i załączniki

Wygasłe połączenie: aktywne połączenie odnawia się samo, gdy jest używane. Połączenie nieużywane przez 30 dni albo takie, które wygasło przed wprowadzeniem tej zasady, trzeba nawiązać ponownie.
Odrzucony załącznik: PlayDrop pobiera pliki tylko z usługi załączników samego hosta. To ograniczenie hostingu plików, a nie ograniczenie dotyczące kraju. Przekaż załącznik rozwiązany przez hosta albo prześlij pliki przez podpisane adresy URL. Nigdy nie wymyślaj download_url ani file_id.