# Errori di caricamento MCP di PlayDrop e come risolverli

La forma degli errori restituiti dagli strumenti MCP di PlayDrop, quando riprovare con lo stesso requestId e la soluzione per ogni codice di errore comune.

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

Ogni errore di uno strumento MCP di PlayDrop mantiene il suo codice `error` stabile ed eventuali dettagli come `path`, `field`, `name` o `expected`, e aggiunge:

- `message`: cosa è andato storto, in parole semplici.
- `retryable`: `true` solo quando la stessa identica chiamata può riuscire più tardi.
- `nextAction`: la correzione concreta.
- `docsUrl` e `documentationTopic`: la guida da leggere, disponibile anche con `get_documentation`.

## Riprova o correggi

- **Errori recuperabili** (guasti temporanei, limiti di frequenza, un completamento interrotto): dopo una breve attesa riprova la stessa identica chiamata con lo stesso `requestId`. Non creare un’altra versione.
- **Risposta persa:** non puoi sapere se ha funzionato, quindi riprova con contenuto identico e lo stesso `requestId`. PlayDrop restituisce il risultato originale invece di pubblicare due volte.
- **Input rifiutato:** correggi prima il campo o il file indicato. Un contenuto modificato richiede un nuovo `requestId`; riprovare con un input invariato fallisce di nuovo.
- **Risultati parziali di un pacchetto:** le voci completate restano pubblicate. Una richiesta corretta deve contenere solo il lavoro non finito.
- **`send_feedback`** non ha una chiave di ripetizione. Dopo un errore ambiguo non inviare di nuovo in automatico: il primo messaggio potrebbe essere arrivato.

## Errori comuni

| Codice | Cosa fare |
|---|---|
| `advanced_upload_required` | Il gioco usa l’SDK, un server, file separati o campi riservati ai pacchetti. Mantieni queste funzioni e carica un [pacchetto](https://www.playdrop.ai/it/create/learn/packaging) con un nuovo `requestId`. |
| `invalid_html_file` | L’HTML è vuoto o supera 10 MiB. Usa un pacchetto per i giochi più grandi. |
| `visibility_required` | Un’app del pacchetto non ha una visibilità. Imposta `visibility` nella richiesta o nell’app: `public`, `unlisted` o `private`. |
| `invalid_visibility` | Usa `public`, `unlisted` o `private`. |
| `visibility_conflict` | La richiesta e una voce di app chiedono visibilità diverse. Indicane una sola, così il pubblico non cambia mai in silenzio. |
| `expected_current_version_required` | Aggiungi il nome di ogni app a `expectedCurrentVersion`: `null` per un nuovo gioco, altrimenti la versione attuale da `list_games`. |
| `current_version_changed` | Qualcuno ha pubblicato una versione più recente. Chiama `list_games`, conferma il gioco con il tuo utente, poi carica con la versione attuale e un nuovo `requestId`. |
| `game_exists_use_id`, `game_not_found` | Chiama `list_games`, usa il `gameId` o il nome giusto e mantieni il nome esistente del gioco. |
| `request_id_content_conflict` | Questo `requestId` appartiene già a un contenuto diverso. Usa un nuovo ID, oppure invia di nuovo il contenuto originale senza modifiche. |
| `catalogue_file_missing_or_invalid` | Un file non è stato caricato o i suoi byte non corrispondono. Chiama di nuovo `prepare_catalogue_upload` con input identico e lo stesso `requestId`, invia con PUT i file mancanti, poi completa di nuovo. |
| `catalogue_files_unclaimed` | Alcuni file non sono usati da nessuna voce del catalogo. Fai riferimento a essi, assegna ai file della scheda `role: "LISTING"` e `app`, oppure rimuovili. |
| `entry_point_missing` | `apps[].file` indica un file che non è stato caricato. Senza `file`, la pagina di ingresso predefinita è `<name>.html`. |
| `archive_catalogue_required` | Metti catalogue.json nella radice dello ZIP, non dentro una cartella. |
| `archive_too_large` | Oltre 20 MiB compresso: estrailo e carica la cartella con URL firmati per ogni file, che consentono fino a 50 MiB per file. Oltre 200 MiB estratto: il gioco stesso è troppo grande per una versione; comprimi o rimuovi degli asset. |
| `procedural_module_validation_unavailable` | I modelli 3D procedurali eseguibili o in formato personalizzato non si possono caricare tramite MCP. Convertili in un formato statico o fai riferimento a un asset pubblicato. |
| `upload_expired`, `upload_cancelled` | Prepara di nuovo il caricamento con un nuovo `requestId` e completalo entro 30 minuti. |
| `invalid_token`, `insufficient_scope` | Ricollega l’account PlayDrop nella tua app di IA e consenti la pubblicazione. |

Gli errori sui campi del catalogo, come un tag, una dichiarazione dei controller o una modalità di gioco non validi, rimandano al [riferimento di catalogue.json](https://www.playdrop.ai/it/create/learn/catalogue-json).

## Connessione e allegati

- **Connessione scaduta:** una connessione attiva si rinnova da sola mentre viene usata. Una connessione inutilizzata per 30 giorni, o scaduta prima di questa regola, va collegata di nuovo.
- **Allegato rifiutato:** PlayDrop scarica file solo dal servizio di allegati dell’host stesso. È una restrizione sull’hosting dei file, non una restrizione per paese. Passa l’allegato risolto dall’host, oppure carica i file con URL firmati. Non inventare mai un `download_url` o un `file_id`.

## Segnala un problema

Se un errore sembra sbagliato o l’azione successiva non funziona, chiama `send_feedback` una sola volta con il nome dello strumento, il codice di errore, cosa hai inviato (senza token né URL firmati) e cosa ti aspettavi.

## Guide correlate

- [Pubblica dalla tua app di IA](https://www.playdrop.ai/it/create/learn/mcp-publishing): Come le app di IA pubblicano su PlayDrop tramite MCP: percorso semplice e pacchetti, test privati, publish_game_version, aggiornamenti, limiti e recupero.
- [Pacchetti e .play](https://www.playdrop.ai/it/create/learn/packaging): Organizza una cartella compilata, uno ZIP o un .play con catalogue.json nella radice, dichiara scheda e server e caricalo con prepare_catalogue_upload.
- [Risoluzione dei problemi](https://www.playdrop.ai/it/create/learn/troubleshooting): Risolvi attività di creazione bloccate, prompt poco chiari, ricompense o guadagni mancanti, limiti di crediti e problemi di importazione dei giochi web.