FAQ de troubleshooting

Soluções para problemas comuns do Synapse.

Não consigo fazer login

Sintomas

• POST /login retorna 401
• "Invalid email or password"

Soluções

1. Verifique se o email está correto — case sensitive
2. Confira a senha — mínimo de 6 caracteres
3. Registre-se primeiro se você não tem uma conta: POST /register
4. Redefina a senha (se SMTP configurado) via interface web

Perdi minha Mind Key

Sintomas

• Não consegue acessar memórias
• A Mind Key foi excluída/perdida

Soluções

Mind Keys não podem ser recuperadas. Você deve:

1. Fazer login para obter JWT: POST /login
2. Listar minds: GET /minds (com JWT)
3. Criar novo mind: POST /minds
4. Salvar a nova Mind Key
5. (Opcional) Excluir mind antigo: DELETE /minds/:id

Dados no mind antigo são perdidos a menos que você encontre a Mind Key.

Chamadas de API retornam 401

Sintomas

• Todas as chamadas de API retornam 401 Unauthorized
• "Mind Key fehlt oder ungültig"

Soluções

1. Verifique o formato do cabeçalho: Authorization: Bearer mk_...
2. Confira se a Mind Key começa com mk_ (não eyJ que é JWT)
3. Teste diretamente:

   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall

4. A Mind Key pode ter sido revogada — crie um novo mind

Consulte Autenticação.

Chamadas de API retornam 404

Sintomas

• 404 Not Found
• "Route not found"

Soluções

1. Confira endpoints válidos: curl https://synapse.schaefer.zone/endpoints
2. Compare a URL exatamente — case sensitive, sem barras no final
3. Confira o método HTTP — GET /memory vs POST /memory são diferentes

Chamadas de API retornam 429

Sintomas

• 429 Too Many Requests
• "Rate limit exceeded"

Soluções

1. Mude para auth por cabeçalho (sem limite de taxa):

   # Don't
   curl ".../memory/recall?key=mk_..."
   
   # Do
   curl -H "Authorization: Bearer mk_..." .../memory/recall

2. Aguarde Retry-After segundos se precisar usar ?key=

Consulte Limites de taxa.

Busca de memória não retorna resultados

Sintomas

• GET /memory/search?q=... retorna vazio
• Sabe que memórias existem

Soluções

1. Verifique se as memórias existem: GET /memory/recall
2. Confira a sintaxe de busca — FTS5 tem sintaxe específica
3. Tente uma consulta mais simples — ?q=docker em vez de ?q=docker+swarm+deployment
4. Use busca semântica para consultas conceituais: GET /memory/semantic-search?q=...

Consulte Busca FTS5.

Memórias não estão persistindo

Sintomas

• POST /memory retorna sucesso
• GET /memory/recall não as mostra

Soluções

1. Verifique se é a mesma Mind Key — keys diferentes = minds diferentes
2. Confira a resposta — POST retorna { "id": "mem_...", "status": "stored" }
3. Tente GET /memory (lista JSON) em vez de /memory/recall (texto)
4. Confira o filtro — ?category= ou ?tag= podem estar ocultando-as

Ferramentas não aparecem no Claude Desktop

Sintomas

• Claude Desktop mostra 0 ferramentas
• Sem ícone 🔌

Soluções

1. Reinicie o Claude Desktop completamente (Cmd+Q)
2. Verifique se o arquivo de config é JSON válido
3. Confirme Node.js 18+ instalado
4. Rode o MCP manualmente: npx -y synapse-mcp-api@latest
5. Confira os logs: ~/Library/Logs/Claude/mcp.log

Consulte MCP Troubleshooting.

Synapse está offline

Sintomas

• Não consegue acessar synapse.schaefer.zone
• curl dá timeout

Soluções

1. Verifique sua internet — tente outro site
2. Confira a saúde do Synapse: curl https://synapse.schaefer.zone/health
3. Aguarde — pode ser outage temporário ou deploy
4. Confira a página de status (se disponível)

Para auto-hospedagem: confira o status do container Docker, conexão com banco.

Erros de banco de dados

Sintomas

• 500 Internal Server Error
• "Database connection failed"

Soluções

Para auto-hospedagem:

1. Verifique se PostgreSQL está rodando: docker ps | grep postgres
2. Confira DATABASE_URL no env
3. Confira as migrations: npm run migrate:check
4. Confira espaço em disco: df -h

Para versão hospedada: reporte ao suporte.

Webhook não dispara

Sintomas

• Registrou webhook mas não recebe callbacks
• Nenhum POST na sua URL

Soluções

1. Verifique se a URL é alcançável: curl -X POST your-url -d '{}'
2. Confira o filtro de eventos — memory.* corresponde a todos os eventos de memória
3. Teste o webhook: POST /webhooks/:id/test
4. Confira se o webhook está habilitado: GET /webhooks/:id
5. Verifique SSL — o Synapse requer HTTPS válido para URLs de webhook

Consulte API de Webhooks.

Cron job não roda

Sintomas

• Criou cron job mas não dispara
• next_run não atualiza

Soluções

1. Confira a sintaxe de agendamento — deve ser cron de 5 campos válido OU inteiro em segundos
2. Verifique se o endpoint é permitido — deve ser http(s), sem IPs privados
3. Confira se o job está habilitado: GET /cron
4. Aguarde o próximo horário agendado — cron não é instantâneo

Consulte Cron & Agendador.

Precisa de mais ajuda?

1. Confira a documentação existente: https://synapse.schaefer.zone/docs
2. Busque na documentação: GET /docs/search?q=your+question
3. Abra uma issue: https://gitlab.com/schaefer-services/synapse/-/issues
4. Contato: consulte a página /support

Próximos passos

• Erros e tratamento de erros
• FAQ da API
• MCP Troubleshooting