# 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**:
   ```bash
   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](/docs/getting-started/authentication).

## Chamadas de API retornam 404

### Sintomas

- 404 Not Found
- "Route not found"

### Soluções

> [!CRITICAL]
> Não tente adivinhar caminhos de endpoint. Apenas os caminhos em
> `GET /endpoints` existem.

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):
   ```bash
   # 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](/docs/api/rate-limits).

## 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](/docs/concepts/fts5-search).

## 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](/docs/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](/docs/api/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](/docs/api/cron).

## 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](/docs/api/errors)
- [FAQ da API](/docs/faq/api-faq)
- [MCP Troubleshooting](/docs/mcp/troubleshooting)