{"title":"FAQ de troubleshooting","slug":"troubleshooting","category":"faq","summary":"Soluções para problemas comuns do Synapse — auth, rede, dados, deploy.","audience":["human","llm"],"tags":["faq","troubleshooting","problems","solutions"],"difficulty":"beginner","updated":"2026-06-27","word_count":718,"read_minutes":4,"lang":"pt","translated":true,"requested_lang":"pt","content_markdown":"\n# FAQ de troubleshooting\n\nSoluções para problemas comuns do Synapse.\n\n## Não consigo fazer login\n\n### Sintomas\n\n- `POST /login` retorna 401\n- \"Invalid email or password\"\n\n### Soluções\n\n1. **Verifique se o email está correto** — case sensitive\n2. **Confira a senha** — mínimo de 6 caracteres\n3. **Registre-se primeiro** se você não tem uma conta: `POST /register`\n4. **Redefina a senha** (se SMTP configurado) via interface web\n\n## Perdi minha Mind Key\n\n### Sintomas\n\n- Não consegue acessar memórias\n- A Mind Key foi excluída/perdida\n\n### Soluções\n\nMind Keys não podem ser recuperadas. Você deve:\n\n1. Fazer login para obter JWT: `POST /login`\n2. Listar minds: `GET /minds` (com JWT)\n3. Criar novo mind: `POST /minds`\n4. Salvar a nova Mind Key\n5. (Opcional) Excluir mind antigo: `DELETE /minds/:id`\n\n**Dados no mind antigo são perdidos** a menos que você encontre a Mind Key.\n\n## Chamadas de API retornam 401\n\n### Sintomas\n\n- Todas as chamadas de API retornam 401 Unauthorized\n- \"Mind Key fehlt oder ungültig\"\n\n### Soluções\n\n1. **Verifique o formato do cabeçalho**: `Authorization: Bearer mk_...`\n2. **Confira se a Mind Key começa com `mk_`** (não `eyJ` que é JWT)\n3. **Teste diretamente**:\n ```bash\n curl -H \"Authorization: Bearer mk_YOUR_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n ```\n4. **A Mind Key pode ter sido revogada** — crie um novo mind\n\nConsulte [Autenticação](/docs/getting-started/authentication).\n\n## Chamadas de API retornam 404\n\n### Sintomas\n\n- 404 Not Found\n- \"Route not found\"\n\n### Soluções\n\n> [!CRITICAL]\n> Não tente adivinhar caminhos de endpoint. Apenas os caminhos em\n> `GET /endpoints` existem.\n\n1. **Confira endpoints válidos**: `curl https://synapse.schaefer.zone/endpoints`\n2. **Compare a URL exatamente** — case sensitive, sem barras no final\n3. **Confira o método HTTP** — `GET /memory` vs `POST /memory` são diferentes\n\n## Chamadas de API retornam 429\n\n### Sintomas\n\n- 429 Too Many Requests\n- \"Rate limit exceeded\"\n\n### Soluções\n\n1. **Mude para auth por cabeçalho** (sem limite de taxa):\n ```bash\n # Don't\n curl \".../memory/recall?key=mk_...\"\n \n # Do\n curl -H \"Authorization: Bearer mk_...\" .../memory/recall\n ```\n2. **Aguarde `Retry-After` segundos** se precisar usar `?key=`\n\nConsulte [Limites de taxa](/docs/api/rate-limits).\n\n## Busca de memória não retorna resultados\n\n### Sintomas\n\n- `GET /memory/search?q=...` retorna vazio\n- Sabe que memórias existem\n\n### Soluções\n\n1. **Verifique se as memórias existem**: `GET /memory/recall`\n2. **Confira a sintaxe de busca** — FTS5 tem sintaxe específica\n3. **Tente uma consulta mais simples** — `?q=docker` em vez de `?q=docker+swarm+deployment`\n4. **Use busca semântica** para consultas conceituais: `GET /memory/semantic-search?q=...`\n\nConsulte [Busca FTS5](/docs/concepts/fts5-search).\n\n## Memórias não estão persistindo\n\n### Sintomas\n\n- POST /memory retorna sucesso\n- GET /memory/recall não as mostra\n\n### Soluções\n\n1. **Verifique se é a mesma Mind Key** — keys diferentes = minds diferentes\n2. **Confira a resposta** — POST retorna `{ \"id\": \"mem_...\", \"status\": \"stored\" }`\n3. **Tente GET /memory** (lista JSON) em vez de /memory/recall (texto)\n4. **Confira o filtro** — `?category=` ou `?tag=` podem estar ocultando-as\n\n## Ferramentas não aparecem no Claude Desktop\n\n### Sintomas\n\n- Claude Desktop mostra 0 ferramentas\n- Sem ícone 🔌\n\n### Soluções\n\n1. **Reinicie o Claude Desktop completamente** (Cmd+Q)\n2. **Verifique se o arquivo de config é JSON válido**\n3. **Confirme Node.js 18+** instalado\n4. **Rode o MCP manualmente**: `npx -y synapse-mcp-api@latest`\n5. **Confira os logs**: `~/Library/Logs/Claude/mcp.log`\n\nConsulte [MCP Troubleshooting](/docs/mcp/troubleshooting).\n\n## Synapse está offline\n\n### Sintomas\n\n- Não consegue acessar synapse.schaefer.zone\n- curl dá timeout\n\n### Soluções\n\n1. **Verifique sua internet** — tente outro site\n2. **Confira a saúde do Synapse**: `curl https://synapse.schaefer.zone/health`\n3. **Aguarde** — pode ser outage temporário ou deploy\n4. **Confira a página de status** (se disponível)\n\nPara auto-hospedagem: confira o status do container Docker, conexão com banco.\n\n## Erros de banco de dados\n\n### Sintomas\n\n- 500 Internal Server Error\n- \"Database connection failed\"\n\n### Soluções\n\nPara auto-hospedagem:\n\n1. **Verifique se PostgreSQL está rodando**: `docker ps | grep postgres`\n2. **Confira DATABASE_URL** no env\n3. **Confira as migrations**: `npm run migrate:check`\n4. **Confira espaço em disco**: `df -h`\n\nPara versão hospedada: reporte ao suporte.\n\n## Webhook não dispara\n\n### Sintomas\n\n- Registrou webhook mas não recebe callbacks\n- Nenhum POST na sua URL\n\n### Soluções\n\n1. **Verifique se a URL é alcançável**: `curl -X POST your-url -d '{}'`\n2. **Confira o filtro de eventos** — `memory.*` corresponde a todos os eventos de memória\n3. **Teste o webhook**: `POST /webhooks/:id/test`\n4. **Confira se o webhook está habilitado**: `GET /webhooks/:id`\n5. **Verifique SSL** — o Synapse requer HTTPS válido para URLs de webhook\n\nConsulte [API de Webhooks](/docs/api/webhooks).\n\n## Cron job não roda\n\n### Sintomas\n\n- Criou cron job mas não dispara\n- `next_run` não atualiza\n\n### Soluções\n\n1. **Confira a sintaxe de agendamento** — deve ser cron de 5 campos válido OU inteiro em segundos\n2. **Verifique se o endpoint é permitido** — deve ser http(s), sem IPs privados\n3. **Confira se o job está habilitado**: `GET /cron`\n4. **Aguarde o próximo horário agendado** — cron não é instantâneo\n\nConsulte [Cron & Agendador](/docs/api/cron).\n\n## Precisa de mais ajuda?\n\n1. **Confira a documentação existente**: \n2. **Busque na documentação**: `GET /docs/search?q=your+question`\n3. **Abra uma issue**: \n4. **Contato**: consulte a página `/support`\n\n## Próximos passos\n\n- [Erros e tratamento de erros](/docs/api/errors)\n- [FAQ da API](/docs/faq/api-faq)\n- [MCP Troubleshooting](/docs/mcp/troubleshooting)\n","content_html":"

FAQ de troubleshooting

\n

Soluções para problemas comuns do Synapse.

\n

Não consigo fazer login

\n

Sintomas

\n\n

Soluções

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

Perdi minha Mind Key

\n

Sintomas

\n\n

Soluções

\n

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

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

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

\n

Chamadas de API retornam 401

\n

Sintomas

\n\n

Soluções

\n
    \n
  1. Verifique o formato do cabeçalho: Authorization: Bearer mk_...
    2. \n
  2. Confira se a Mind Key começa com mk_ (não eyJ que é JWT)
    3. \n
  3. Teste diretamente:
    curl -H "Authorization: Bearer mk_YOUR_KEY" \\\n     https://synapse.schaefer.zone/memory/recall
    4. \n
  4. A Mind Key pode ter sido revogada — crie um novo mind
    5. \n
\n

Consulte Autenticação.

\n

Chamadas de API retornam 404

\n

Sintomas

\n\n

Soluções

\n
Não tente adivinhar caminhos de endpoint. Apenas os caminhos em\n`GET /endpoints` existem.
    \n
  1. Confira endpoints válidos: curl https://synapse.schaefer.zone/endpoints
    2. \n
  2. Compare a URL exatamente — case sensitive, sem barras no final
    3. \n
  3. Confira o método HTTP — GET /memory vs POST /memory são diferentes
    4. \n
\n

Chamadas de API retornam 429

\n

Sintomas

\n\n

Soluções

\n
    \n
  1. Mude para auth por cabeçalho (sem limite de taxa):
    # Don't\ncurl ".../memory/recall?key=mk_..."\n\n# Do\ncurl -H "Authorization: Bearer mk_..." .../memory/recall
    2. \n
  2. Aguarde Retry-After segundos se precisar usar ?key=
    3. \n
\n

Consulte Limites de taxa.

\n

Busca de memória não retorna resultados

\n

Sintomas

\n\n

Soluções

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

Consulte Busca FTS5.

\n

Memórias não estão persistindo

\n

Sintomas

\n\n

Soluções

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

Ferramentas não aparecem no Claude Desktop

\n

Sintomas

\n\n

Soluções

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

Consulte MCP Troubleshooting.

\n

Synapse está offline

\n

Sintomas

\n\n

Soluções

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

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

\n

Erros de banco de dados

\n

Sintomas

\n\n

Soluções

\n

Para auto-hospedagem:

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

Para versão hospedada: reporte ao suporte.

\n

Webhook não dispara

\n

Sintomas

\n\n

Soluções

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

Consulte API de Webhooks.

\n

Cron job não roda

\n

Sintomas

\n\n

Soluções

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

Consulte Cron & Agendador.

\n

Precisa de mais ajuda?

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

Próximos passos

\n\n","urls":{"html":"/docs/faq/troubleshooting","text":"/docs/faq/troubleshooting?format=text","json":"/docs/faq/troubleshooting?format=json","llm":"/docs/faq/troubleshooting?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}