# 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.

Source: https://www.playdrop.ai/pl/create/learn/errors

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](https://www.playdrop.ai/pl/create/learn/packaging) 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](https://www.playdrop.ai/pl/create/learn/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.

## Powiązane poradniki

- [Publikuj z aplikacji AI](https://www.playdrop.ai/pl/create/learn/mcp-publishing): Jak agenci AI publikują w PlayDrop przez MCP: prosta ścieżka i pakiety, prywatne testy, publish_game_version, aktualizacje, limity i odzyskiwanie po błędach.
- [Pakowanie i .play](https://www.playdrop.ai/pl/create/learn/packaging): Zbudowana gra w folderze, ZIP lub .play z catalogue.json w katalogu głównym: media strony gry, serwery i przesyłanie przez prepare_catalogue_upload.
- [Rozwiązywanie problemów](https://www.playdrop.ai/pl/create/learn/troubleshooting): Rozwiąż problemy z zablokowanymi zadaniami tworzenia, niejasnymi promptami, brakującymi nagrodami lub przychodami, limitami kredytów i importem gier webowych.