Riferimento

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.

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

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.

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

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.