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

FAQ de solución de problemas

\n

Soluciones a problemas comunes de Synapse.

\n

No puedo iniciar sesión

\n

Síntomas

\n\n

Soluciones

\n
    \n
  1. Verifique que el email es correcto — sensible a mayúsculas/minúsculas
    2. \n
  2. Compruebe la contraseña — mínimo 6 caracteres
    3. \n
  3. Regístrese primero si no tiene cuenta: POST /register
    4. \n
  4. Restablezca la contraseña (si SMTP está configurado) vía la interfaz web
    5. \n
\n

Perdí mi Mind Key

\n

Síntomas

\n\n

Soluciones

\n

Los Mind Keys no se pueden recuperar. Debe:

\n
    \n
  1. Iniciar sesión para obtener JWT: POST /login
    2. \n
  2. Listar minds: GET /minds (con JWT)
    3. \n
  3. Crear un nuevo mind: POST /minds
    4. \n
  4. Guardar el nuevo Mind Key
    5. \n
  5. (Opcional) Eliminar el mind antiguo: DELETE /minds/:id
    6. \n
\n

Los datos del mind antiguo se pierden a menos que encuentre el Mind Key.

\n

Las llamadas a la API devuelven 401

\n

Síntomas

\n\n

Soluciones

\n
    \n
  1. Verifique el formato de la cabecera: Authorization: Bearer mk_...
    2. \n
  2. Compruebe que el Mind Key empieza por mk_ (no eyJ, que es JWT)
    3. \n
  3. Pruebe directamente:
    curl -H "Authorization: Bearer mk_YOUR_KEY" \\\n     https://synapse.schaefer.zone/memory/recall
    4. \n
  4. El Mind Key puede estar revocado — cree un nuevo mind
    5. \n
\n

Consulte Autenticación.

\n

Las llamadas a la API devuelven 404

\n

Síntomas

\n\n

Soluciones

\n
No adivine las rutas de los endpoints. Solo existen las rutas en\n`GET /endpoints`.
    \n
  1. Compruebe los endpoints válidos: curl https://synapse.schaefer.zone/endpoints
    2. \n
  2. Compare la URL exactamente — sensible a mayúsculas/minúsculas, sin barras finales
    3. \n
  3. Verifique el método HTTP — GET /memory vs POST /memory son diferentes
    4. \n
\n

Las llamadas a la API devuelven 429

\n

Síntomas

\n\n

Soluciones

\n
    \n
  1. Cambie a auth por cabecera (sin límite de frecuencia):
    # Don't\ncurl ".../memory/recall?key=mk_..."\n\n# Do\ncurl -H "Authorization: Bearer mk_..." .../memory/recall
    2. \n
  2. Espere Retry-After segundos si debe usar ?key=
    3. \n
\n

Consulte Límites de frecuencia.

\n

La búsqueda de memoria no devuelve resultados

\n

Síntomas

\n\n

Soluciones

\n
    \n
  1. Verifique que existen memorias: GET /memory/recall
    2. \n
  2. Compruebe la sintaxis de búsqueda — FTS5 tiene sintaxis específica
    3. \n
  3. Pruebe una consulta más simple — ?q=docker en lugar de ?q=docker+swarm+deployment
    4. \n
  4. Use búsqueda semántica para consultas conceptuales: GET /memory/semantic-search?q=...
    5. \n
\n

Consulte Búsqueda FTS5.

\n

Las memorias no persisten

\n

Síntomas

\n\n

Soluciones

\n
    \n
  1. Verifique el mismo Mind Key — claves diferentes = minds diferentes
    2. \n
  2. Compruebe la respuesta — POST devuelve { "id": "mem_...", "status": "stored" }
    3. \n
  3. Pruebe GET /memory (lista JSON) en lugar de /memory/recall (texto)
    4. \n
  4. Revise el filtro — ?category= o ?tag= pueden estar ocultándolas
    5. \n
\n

Las herramientas no aparecen en Claude Desktop

\n

Síntomas

\n\n

Soluciones

\n
    \n
  1. Reinicie Claude Desktop completamente (Cmd+Q)
    2. \n
  2. Verifique que el archivo de configuración es JSON válido
    3. \n
  3. Compruebe Node.js 18+ instalado
    4. \n
  4. Ejecute MCP manualmente: npx -y synapse-mcp-api@latest
    5. \n
  5. Revise los logs: ~/Library/Logs/Claude/mcp.log
    6. \n
\n

Consulte Solución de problemas de MCP.

\n

Synapse está fuera de línea

\n

Síntomas

\n\n

Soluciones

\n
    \n
  1. Compruebe su internet — pruebe otro sitio
    2. \n
  2. Verifique la salud de Synapse: curl https://synapse.schaefer.zone/health
    3. \n
  3. Espere — puede ser una interrupción temporal o un despliegue
    4. \n
  4. Consulte la página de estado (si está disponible)
    5. \n
\n

Para autoalojamiento: compruebe el estado del contenedor Docker y la conexión a\nla base de datos.

\n

Errores de base de datos

\n

Síntomas

\n\n

Soluciones

\n

Para autoalojamiento:

\n
    \n
  1. Compruebe que PostgreSQL está corriendo: docker ps | grep postgres
    2. \n
  2. Verifique DATABASE_URL en el entorno
    3. \n
  3. Revise las migraciones: npm run migrate:check
    4. \n
  4. Compruebe el espacio en disco: df -h
    5. \n
\n

Para la versión alojada: reporte a soporte.

\n

El webhook no se dispara

\n

Síntomas

\n\n

Soluciones

\n
    \n
  1. Verifique que la URL es alcanzable: curl -X POST your-url -d '{}'
    2. \n
  2. Compruebe el filtro de eventos — memory.* coincide con todos los eventos de memoria
    3. \n
  3. Pruebe el webhook: POST /webhooks/:id/test
    4. \n
  4. Compruebe que el webhook está habilitado: GET /webhooks/:id
    5. \n
  5. Verifique el SSL — Synapse requiere HTTPS válido para las URLs de webhook
    6. \n
\n

Consulte API de Webhooks.

\n

El trabajo cron no se ejecuta

\n

Síntomas

\n\n

Soluciones

\n
    \n
  1. Compruebe la sintaxis de programación — debe ser cron de 5 campos válido O segundos enteros
    2. \n
  2. Verifique que el endpoint está permitido — debe ser http(s), sin IPs privadas
    3. \n
  3. Compruebe que el trabajo está habilitado: GET /cron
    4. \n
  4. Espere a la próxima hora programada — cron no es instantáneo
    5. \n
\n

Consulte Cron y Scheduler.

\n

¿Necesita más ayuda?

\n
    \n
  1. Consulte la documentación existente: https://synapse.schaefer.zone/docs
    2. \n
  2. Busque en la docs: GET /docs/search?q=your+question
    3. \n
  3. Abra un issue: https://gitlab.com/schaefer-services/synapse/-/issues
    4. \n
  4. Contacto: consulte la página /support
    5. \n
\n

Próximos pasos

\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"]}