# Erros de envio do MCP do PlayDrop e como se recuperar

O formato de erro das ferramentas MCP do PlayDrop, quando repetir com o mesmo requestId e a correção para cada código de erro comum.

Source: https://www.playdrop.ai/pt-br/create/learn/errors

Todo erro de uma ferramenta MCP do PlayDrop mantém seu código `error` estável e detalhes como `path`, `field`, `name` ou `expected`, e acrescenta:

- `message`: o que deu errado, em palavras simples.
- `retryable`: `true` só quando a chamada idêntica pode dar certo mais tarde.
- `nextAction`: a correção concreta.
- `docsUrl` e `documentationTopic`: o guia a ler, também disponível com `get_documentation`.

## Repetir ou corrigir

- **Erros que podem ser repetidos** (falhas temporárias, limites de taxa, uma conclusão interrompida): repita a chamada idêntica com o mesmo `requestId` depois de uma breve espera. Não crie outra versão.
- **Resposta perdida:** você não sabe se funcionou, então repita o conteúdo idêntico com o mesmo `requestId`. O PlayDrop retorna o resultado original em vez de publicar duas vezes.
- **Entrada recusada:** corrija primeiro o campo ou o arquivo indicado. Conteúdo alterado precisa de um novo `requestId`; repetir uma entrada sem alterações falha de novo.
- **Resultados parciais de pacote:** os itens concluídos continuam publicados. Uma solicitação corrigida deve conter só o trabalho não concluído.
- **`send_feedback`** não tem chave de repetição. Depois de uma falha ambígua, não reenvie automaticamente: a primeira mensagem pode ter chegado.

## Erros comuns

| Código | O que fazer |
|---|---|
| `advanced_upload_required` | O jogo usa o SDK, um servidor, arquivos separados ou campos exclusivos de pacote. Mantenha esses recursos e envie um [pacote](https://www.playdrop.ai/pt-br/create/learn/packaging) com um novo `requestId`. |
| `invalid_html_file` | O HTML está vazio ou tem mais de 10 MiB. Use um pacote para jogos maiores. |
| `visibility_required` | Um jogo do pacote não tem visibilidade. Defina `visibility` na solicitação ou no jogo: `public`, `unlisted` ou `private`. |
| `invalid_visibility` | Use `public`, `unlisted` ou `private`. |
| `visibility_conflict` | A solicitação e uma entrada de jogo pedem visibilidades diferentes. Informe só uma, para que o público nunca mude sem aviso. |
| `expected_current_version_required` | Adicione o nome de cada jogo a `expectedCurrentVersion`: `null` para um jogo novo; caso contrário, a versão atual retornada por `list_games`. |
| `current_version_changed` | Alguém publicou uma versão mais recente. Chame `list_games`, confirme o jogo de destino com a pessoa com quem você trabalha e depois envie com a versão atual e um novo `requestId`. |
| `game_exists_use_id`, `game_not_found` | Chame `list_games`, use o `gameId` ou o nome certo e mantenha o nome atual do jogo. |
| `request_id_content_conflict` | Este `requestId` já pertence a outro conteúdo. Use um novo ID ou reenvie o conteúdo original sem alterações. |
| `catalogue_file_missing_or_invalid` | Um arquivo não foi enviado ou os bytes dele não correspondem. Chame `prepare_catalogue_upload` de novo com a entrada idêntica e o mesmo `requestId`, faça o PUT dos arquivos que faltam e conclua de novo. |
| `catalogue_files_unclaimed` | Alguns arquivos não são usados por nenhuma entrada do catálogo. Faça referência a eles, dê aos arquivos da listagem `role: "LISTING"` e `app`, ou remova-os. |
| `entry_point_missing` | `apps[].file` indica um arquivo que não foi enviado. Sem `file`, o padrão da entrada é `<name>.html`. |
| `archive_catalogue_required` | Coloque o catalogue.json na raiz do ZIP, não dentro de uma pasta. |
| `archive_too_large` | Mais de 20 MiB compactado: descompacte e envie a pasta com arquivos assinados, o que permite até 50 MiB por arquivo. Mais de 200 MiB descompactado: o próprio jogo é grande demais para uma versão; comprima ou remova assets. |
| `procedural_module_validation_unavailable` | Modelos 3D procedurais executáveis ou de formato personalizado não podem ser enviados pelo MCP. Converta-os em arquivos fixos (bake) ou faça referência a um asset publicado. |
| `upload_expired`, `upload_cancelled` | Prepare o envio de novo com um novo `requestId` e conclua-o em até 30 minutos. |
| `invalid_token`, `insufficient_scope` | Conecte de novo a conta do PlayDrop no seu app de IA e permita a publicação. |

Erros de campos do catálogo, como uma tag inválida, uma declaração de controle ou um modo de jogador, apontam para a [referência do catalogue.json](https://www.playdrop.ai/pt-br/create/learn/catalogue-json).

## Conexão e anexos

- **Conexão expirada:** uma conexão ativa se renova sozinha enquanto é usada. Uma conexão sem uso por 30 dias, ou que expirou antes desta regra, precisa ser conectada de novo.
- **Anexo recusado:** o PlayDrop só baixa arquivos do próprio serviço de anexos do host. É uma restrição do serviço de arquivos, não uma restrição de país. Passe o anexo resolvido pelo host ou envie os arquivos com URLs assinadas. Nunca invente um `download_url` ou `file_id`.

## Relate um problema

Se um erro parecer errado ou a próxima ação não funcionar, chame `send_feedback` uma vez com o nome da ferramenta, o código de erro, o que você enviou (sem tokens nem URLs assinadas) e o que você esperava.

## Guias relacionados

- [Publicar pelo seu app de IA](https://www.playdrop.ai/pt-br/create/learn/mcp-publishing): Como agentes de IA publicam no PlayDrop por MCP: caminho simples e de pacote, testes privados, publish_game_version, atualizações, limites e recuperação.
- [Empacotamento e .play](https://www.playdrop.ai/pt-br/create/learn/packaging): Organize uma pasta, ZIP ou .play compilado com o catalogue.json na raiz, declare a mídia da listagem e os servidores e envie com prepare_catalogue_upload.
- [Solução de problemas](https://www.playdrop.ai/pt-br/create/learn/troubleshooting): Resolva tarefas bloqueadas, pedidos pouco claros, recompensas ou ganhos ausentes, limites de Créditos e erros de importação web.