# FAQ de solución de problemas Soluciones a problemas comunes de Synapse. ## No puedo iniciar sesión ### Síntomas - `POST /login` devuelve 401 - "Invalid email or password" ### Soluciones 1. **Verifique que el email es correcto** — sensible a mayúsculas/minúsculas 2. **Compruebe la contraseña** — mínimo 6 caracteres 3. **Regístrese primero** si no tiene cuenta: `POST /register` 4. **Restablezca la contraseña** (si SMTP está configurado) vía la interfaz web ## Perdí mi Mind Key ### Síntomas - No puede acceder a las memorias - El Mind Key se eliminó/perdió ### Soluciones Los Mind Keys no se pueden recuperar. Debe: 1. Iniciar sesión para obtener JWT: `POST /login` 2. Listar minds: `GET /minds` (con JWT) 3. Crear un nuevo mind: `POST /minds` 4. Guardar el nuevo Mind Key 5. (Opcional) Eliminar el mind antiguo: `DELETE /minds/:id` **Los datos del mind antiguo se pierden** a menos que encuentre el Mind Key. ## Las llamadas a la API devuelven 401 ### Síntomas - Todas las llamadas a la API devuelven 401 Unauthorized - "Mind Key fehlt oder ungültig" ### Soluciones 1. **Verifique el formato de la cabecera**: `Authorization: Bearer mk_...` 2. **Compruebe que el Mind Key empieza por `mk_`** (no `eyJ`, que es JWT) 3. **Pruebe directamente**: ```bash curl -H "Authorization: Bearer mk_YOUR_KEY" \ https://synapse.schaefer.zone/memory/recall ``` 4. **El Mind Key puede estar revocado** — cree un nuevo mind Consulte [Autenticación](/docs/getting-started/authentication). ## Las llamadas a la API devuelven 404 ### Síntomas - 404 Not Found - "Route not found" ### Soluciones > [!CRITICAL] > No adivine las rutas de los endpoints. Solo existen las rutas en > `GET /endpoints`. 1. **Compruebe los endpoints válidos**: `curl https://synapse.schaefer.zone/endpoints` 2. **Compare la URL exactamente** — sensible a mayúsculas/minúsculas, sin barras finales 3. **Verifique el método HTTP** — `GET /memory` vs `POST /memory` son diferentes ## Las llamadas a la API devuelven 429 ### Síntomas - 429 Too Many Requests - "Rate limit exceeded" ### Soluciones 1. **Cambie a auth por cabecera** (sin límite de frecuencia): ```bash # Don't curl ".../memory/recall?key=mk_..." # Do curl -H "Authorization: Bearer mk_..." .../memory/recall ``` 2. **Espere `Retry-After` segundos** si debe usar `?key=` Consulte [Límites de frecuencia](/docs/api/rate-limits). ## La búsqueda de memoria no devuelve resultados ### Síntomas - `GET /memory/search?q=...` devuelve vacío - Sabe que existen memorias ### Soluciones 1. **Verifique que existen memorias**: `GET /memory/recall` 2. **Compruebe la sintaxis de búsqueda** — FTS5 tiene sintaxis específica 3. **Pruebe una consulta más simple** — `?q=docker` en lugar de `?q=docker+swarm+deployment` 4. **Use búsqueda semántica** para consultas conceptuales: `GET /memory/semantic-search?q=...` Consulte [Búsqueda FTS5](/docs/concepts/fts5-search). ## Las memorias no persisten ### Síntomas - POST /memory devuelve éxito - GET /memory/recall no las muestra ### Soluciones 1. **Verifique el mismo Mind Key** — claves diferentes = minds diferentes 2. **Compruebe la respuesta** — POST devuelve `{ "id": "mem_...", "status": "stored" }` 3. **Pruebe GET /memory** (lista JSON) en lugar de /memory/recall (texto) 4. **Revise el filtro** — `?category=` o `?tag=` pueden estar ocultándolas ## Las herramientas no aparecen en Claude Desktop ### Síntomas - Claude Desktop muestra 0 herramientas - Sin icono 🔌 ### Soluciones 1. **Reinicie Claude Desktop completamente** (Cmd+Q) 2. **Verifique que el archivo de configuración es JSON válido** 3. **Compruebe Node.js 18+** instalado 4. **Ejecute MCP manualmente**: `npx -y synapse-mcp-api@latest` 5. **Revise los logs**: `~/Library/Logs/Claude/mcp.log` Consulte [Solución de problemas de MCP](/docs/mcp/troubleshooting). ## Synapse está fuera de línea ### Síntomas - No puede alcanzar synapse.schaefer.zone - curl agota el tiempo de espera ### Soluciones 1. **Compruebe su internet** — pruebe otro sitio 2. **Verifique la salud de Synapse**: `curl https://synapse.schaefer.zone/health` 3. **Espere** — puede ser una interrupción temporal o un despliegue 4. **Consulte la página de estado** (si está disponible) Para autoalojamiento: compruebe el estado del contenedor Docker y la conexión a la base de datos. ## Errores de base de datos ### Síntomas - 500 Internal Server Error - "Database connection failed" ### Soluciones Para autoalojamiento: 1. **Compruebe que PostgreSQL está corriendo**: `docker ps | grep postgres` 2. **Verifique DATABASE_URL** en el entorno 3. **Revise las migraciones**: `npm run migrate:check` 4. **Compruebe el espacio en disco**: `df -h` Para la versión alojada: reporte a soporte. ## El webhook no se dispara ### Síntomas - Webhook registrado pero no recibe callbacks - Sin POST a su URL ### Soluciones 1. **Verifique que la URL es alcanzable**: `curl -X POST your-url -d '{}'` 2. **Compruebe el filtro de eventos** — `memory.*` coincide con todos los eventos de memoria 3. **Pruebe el webhook**: `POST /webhooks/:id/test` 4. **Compruebe que el webhook está habilitado**: `GET /webhooks/:id` 5. **Verifique el SSL** — Synapse requiere HTTPS válido para las URLs de webhook Consulte [API de Webhooks](/docs/api/webhooks). ## El trabajo cron no se ejecuta ### Síntomas - Trabajo cron creado pero no se dispara - `next_run` no se actualiza ### Soluciones 1. **Compruebe la sintaxis de programación** — debe ser cron de 5 campos válido O segundos enteros 2. **Verifique que el endpoint está permitido** — debe ser http(s), sin IPs privadas 3. **Compruebe que el trabajo está habilitado**: `GET /cron` 4. **Espere a la próxima hora programada** — cron no es instantáneo Consulte [Cron y Scheduler](/docs/api/cron). ## ¿Necesita más ayuda? 1. **Consulte la documentación existente**: 2. **Busque en la docs**: `GET /docs/search?q=your+question` 3. **Abra un issue**: 4. **Contacto**: consulte la página `/support` ## Próximos pasos - [Errores y manejo de errores](/docs/api/errors) - [FAQ de la API](/docs/faq/api-faq) - [Solución de problemas de MCP](/docs/mcp/troubleshooting)