# Resolva problemas de conexões API, CLI e MCP

URL canônica: https://sosoapi.ai/pt-br/docs/troubleshooting

Resolva falhas de login, permissão, schema, envio e gravações incertas sem expor credenciais nem duplicar trabalho aceito.

## Navegador errado ou login local bloqueado

Interrompa o login pendente e execute auth login --no-open. Abra a nova URL impressa no perfil de navegador desejado. Confira conta e workspace antes de conceder acesso e use apenas um perfil de navegador para esse link de login. Se a porta 8789 estiver ocupada, identifique o processo que a escuta e interrompa-o somente se for um processo de login iniciado por você.

```
npx sosoapi auth login --no-open
```

```
lsof -nP -iTCP:8789 -sTCP:LISTEN
```

## 401, 403 e contas indisponíveis

Para 401, confira se fez login com uma credencial atual. Para 403, confira a função no workspace, o escopo selecionado e a capacidade exigida pela operação. Use auth status e verifique o e-mail da conta e o tipo de credencial aceito. Altere o acesso somente se a operação precisar; mudar o perfil de ferramentas não concede permissão.

Confira a conta social separadamente. Consulte conexão e capacidades e reconecte somente se o provedor exigir novo consentimento. Um erro interno do serviço não é motivo para recriar uma conexão íntegra.

- [Autenticação e permissões](https://sosoapi.ai/pt-br/docs/authentication)

- [Referência completa da API](https://sosoapi.ai/pt-br/docs/api)

## Validação 400 e divergência de versões

Leia o corpo da resposta e os caminhos dos campos de validação. Erros de validação podem conter ZodError; erros do handler podem usar os campos error, message e code. Compare a requisição com o contrato instalado e atualize o pacote do cliente se necessário. Corrija os campos indicados no erro sem remover valores obrigatórios nem adicionar filtros incompatíveis.

```
npx sosoapi api contract --route /studio-api/scheduled-posts/
```

## 409, 429, 5xx ou uma gravação com timeout

Para 409, consulte a versão mais recente do recurso e as ações disponíveis antes de alterá-lo. Para 429, aguarde conforme Retry-After e reduza a concorrência. Se uma gravação expirar ou retornar 5xx, mantenha seu ID e confira primeiro o resultado existente: o servidor pode tê-la aceitado antes de a conexão falhar.

Repita somente quando a operação e seu estado atual permitirem. Mantenha a mesma chave para o mesmo payload e não crie uma substituição para contornar um resultado incerto. Corrija falhas de autenticação antes de repetir. Se um job em segundo plano ainda estiver pendente, seu status já pode conter um erro de execução que merece consulta.

- [Referência de publicação](https://sosoapi.ai/pt-br/docs/publishing-api-reference)

## Problemas de envio ou descoberta de ferramentas

O envio local aceita arquivos de mídia compatíveis de até 500 MiB do diretório de trabalho, pasta temporária, Pictures/Movies/Videos ou pastas listadas em SOSOAPI_UPLOAD_ROOTS. Pastas iniciadas por ponto e links simbólicos que escapam dessas raízes são recusados. Adicione a pasta específica de mídia necessária em vez de todo o diretório pessoal. Uma conexão HTTP não pode ler arquivos locais.

Se faltarem ferramentas, reconecte o cliente e compare seu perfil e tipo de conexão com a referência. Confira se as ferramentas estão carregadas na conversa atual; apenas um nome de servidor salvo não confirma isso.

- [Referência de ferramentas MCP](https://sosoapi.ai/pt-br/docs/mcp)

## Compartilhe diagnósticos úteis com segurança

Compartilhe nome da operação, horário, status HTTP, código de erro seguro e request_id ou x-request-id, se disponível. Inclua a versão da CLI e se usou MCP local ou remoto. Remova tokens, cookies, links de autorização, URLs assinadas de mídia, conteúdo de clientes e IDs privados. Compartilhe o erro relevante em vez de um arquivo de credenciais ou resposta inteira.

- [Fale com o SosoAPI](https://sosoapi.ai/pt-br/contact)