Saturn Studio – Troubleshooting

ROCKETBOT — SATURN STUDIO

Guía de Troubleshooting

Diagnóstico y solución de errores frecuentes en Saturn Studio

Nota: Estructura — Este documento cubre: errores de credenciales y autenticación, problemas de conectividad con bases de datos, fallos de webhooks, errores de IA y módulos, problemas de flujo y lógica, y una guía de diagnóstico paso a paso.

Atención: Antes de reportar un error a soporte — Revisa siempre el Log de ejecución del agente. El 90% de los errores tienen su causa exacta en el mensaje del log.

Cómo leer el Log de ejecución

El Log es tu primera herramienta de diagnóstico. Antes de revisar cualquier otro lugar, abre el panel de log del agente.

Indicador	Qué significa	Qué hacer
ERROR	El agente falló en esa moon. La causa exacta aparece en el mensaje.	Leer el mensaje de error completo — no solo el tipo.
WARNING	Algo no funcionó perfectamente pero el flujo continuó.	Revisar si el resultado del comando es el esperado.
INFO	Registro informativo del estado del flujo.	Útil para rastrear por dónde pasó el agente.
Moon iluminada en rojo	La moon falló durante la ejecución.	Hacer clic derecho → Ejecutar solo ese comando para aislar el problema.
Agente se detiene sin error	Una condición If/Else dirigió el flujo a un End sin procesamiento.	Revisar las condiciones de bifurcación y los valores de las variables.

Errores por categoría

Categoría 1 — Credenciales y Autenticación

Código y Severidad	Error / Problema	Causas probables	Solución paso a paso	Cómo prevenirlo
ERR-CRED-01 Alto	Credencial falla al hacer Check — estado ‘Not Connected’	• API Key incorrecta o copiada con espacios adicionales. • Clave regenerada en origen pero no actualizada en la plataforma. • Cuenta externa sin plan con acceso API (ej: OpenAI sin crédito).	1. Ir a Credentials y abrir la credencial. 2. Copiar de nuevo la API Key desde el origen (sin espacios). 3. Hacer clic en Check. 4. Si dice ‘quota exceeded’ o ‘billing’, revisar la cuenta externa.	Después de copiar claves, usar Ctrl+A y revisar que no haya espacios al inicio o final. Nunca copiar desde un documento intermedio.
ERR-CRED-02 Alto	OAuth 2.0 rechaza la conexión — Redirect URI mismatch	• El Redirect URI configurado en la app del proveedor (LinkedIn, Mercado Libre, Google, Zoom) no coincide exactamente con Saturn Studio. • La URL tiene mayúsculas, barras finales o parámetros incorrectos.	1. Ir al portal de desarrolladores del servicio. 2. Buscar la sección de Redirect URIs o Authorized redirect URLs. 3. Verificar que la URL sea exactamente: https://studio.rocketbot.com 4. Guardar y reintentar la autenticación.	Copiar la URL de redirect desde la documentación oficial de Saturn Studio, nunca escribirla manualmente.
ERR-CRED-03 Medio	Credencial de Xperience falla — error de API Key inválida	• La API Key del Orquestador venció (vigencia de 2 años). • Nueva API Key generada en el Orquestador pero no actualizada en Saturn Studio. • Usuario del Orquestador sin servicio Xperience contratado.	1. Ingresar al Orquestador Rocketbot. 2. Ir al perfil del usuario → sección API Key. 3. Generar una nueva API Key si la actual está vencida. 4. Copiar la clave y actualizar la credencial de Xperience.	Anotar la fecha de creación de cada API Key del Orquestador para anticipar el vencimiento a los 2 años.
ERR-CRED-04 Medio	Credencial compartida revocada — agentes del equipo fallan	• Un administrador revocó el acceso a una credencial compartida. • El usuario que creó la credencial la eliminó.	1. Identificar al propietario en la lista de Credentials. 2. Solicitar al propietario que vuelva a compartirla por equipo o email. 3. O bien, crear una credencial propia y actualizar los agentes.	Al revocar acceso, notificar al equipo con anticipación. Usar Variables de tipo Credential para facilitar el cambio.

Categoría 2 — Bases de Datos

Código y Severidad	Error / Problema	Causas probables	Solución paso a paso	Cómo prevenirlo
ERR-DB-01 Crítico	No se puede conectar a MySQL o PostgreSQL	• Se usó ‘localhost’ o ‘127.0.0.1’ como dirección. • Puerto 3306 (MySQL) o 5432 (PostgreSQL) bloqueado por el firewall. • El servidor no acepta conexiones externas.	1. Reemplazar ‘localhost’ por la IP pública o dominio del servidor. 2. Verificar puerto abierto para conexiones TCP entrantes. 3. En MySQL: bind-address debe ser 0.0.0.0 en my.cnf. 4. En PostgreSQL: revisar pg_hba.conf y listen_addresses = ‘*’. 5. Usar Test Connection.	Nunca usar localhost como servidor. Saturn Studio opera en la nube y no tiene acceso a redes locales.
ERR-DB-02 Alto	Error de permisos al ejecutar consulta en la base de datos	• El usuario de la base de datos no tiene permisos suficientes (SELECT, INSERT, UPDATE, DELETE). • Intento de acceso a una tabla no autorizada.	1. Conectarse al servidor como administrador. 2. Verificar permisos: SHOW GRANTS FOR ‘usuario’@’%’; (MySQL). 3. Otorgar permisos: GRANT SELECT, INSERT ON base.tabla TO ‘usuario’@’%’; 4. Recargar: FLUSH PRIVILEGES; 5. Probar de nuevo en Saturn Studio.	Crear un usuario dedicado para Saturn Studio con permisos mínimos necesarios. Nunca usar el usuario administrador sa o root.
ERR-DB-03 Alto	SQL Server — falla la conexión por certificado TLS	• Encrypt Connection = True pero el servidor tiene un certificado autofirmado. • Trust Server Certificate = False en desarrollo con certificado no válido.	1. En desarrollo: activar Trust Server Certificate = True en la credencial. 2. En producción: instalar un certificado válido firmado por una CA conocida. 3. Verificar TCP/IP habilitado en SQL Server Configuration Manager. 4. Confirmar puerto 1433 abierto en el firewall.	En producción nunca usar Trust Server Certificate = True. Instalar un certificado válido.

Categoría 3 — Webhooks

Código y Severidad	Error / Problema	Causas probables	Solución paso a paso	Cómo prevenirlo
ERR-WH-01 Alto	El webhook no recibe eventos del servicio externo	• URL del webhook mal pegada en la plataforma externa. • El método HTTP en Saturn Studio no coincide con el del servicio externo (ej: GET vs POST). • El servicio externo requiere verificación inicial (challenge).	1. Ir a Webhooks en Saturn Studio. 2. Copiar la URL exacta del webhook desde el panel. 3. Pegarla de nuevo en la configuración del servicio externo. 4. Verificar que el HTTP Method coincida. 5. Si requiere verificación, usar Response Mode = Immediately.	Usar el panel de monitoreo de Webhooks en Saturn Studio para ver si los eventos están llegando aunque el agente falle.
ERR-WH-02 Medio	El webhook recibe el evento pero el agente no procesa	• El campo ‘Assign result to Variable’ no está configurado. • La variable de guardado no se usa correctamente en el flujo. • El formato del body es diferente al esperado (ej: form-data vs JSON).	1. Abrir monitoreo de Webhooks y hacer clic en el ojo azul del evento. 2. Revisar el campo Body para ver los datos exactos. 3. Comparar la estructura del JSON recibido con lo esperado. 4. Ajustar las referencias y el campo ‘Assign result to Variable’.	Siempre testear el webhook enviando un payload de prueba antes de conectar el flujo completo.
ERR-WH-03 Medio	El servicio externo reporta que el webhook no responde (timeout)	• El agente tarda demasiado en ejecutarse y el proveedor corta la conexión. • Response Mode está configurado como ‘After robot execution’ en lugar de ‘Immediately’.	1. Cambiar Response Mode a ‘Immediately’ para responder al instante. 2. Mover el procesamiento pesado después de confirmar la recepción. 3. Si se requiere un payload específico, usar ‘Send Webhook Response’.	La mayoría de proveedores tienen timeouts de 5 a 30 segundos. Responder inmediatamente y procesar en segundo plano.

Categoría 4 — Módulos de Inteligencia Artificial

Código y Severidad	Error / Problema	Causas probables	Solución paso a paso	Cómo prevenirlo
ERR-AI-01 Alto	OpenAI devuelve error 429 — Rate limit exceeded	• Demasiadas peticiones enviadas en poco tiempo. • El plan de OpenAI tiene un límite bajo de requests por minuto (RPM). • Un loop llama a OpenAI sin esperas entre iteraciones.	1. Agregar una moon de espera (Wait / Sleep) en los loops. 2. Considerar aumentar el plan de OpenAI si el uso es alto. 3. Implementar patrón de reintento con espera exponencial (1s, 2s, 4s). 4. Revisar la cantidad de llamadas en el log.	Nunca llamar a APIs de IA en loops sin control de cadencia. Agregar siempre una espera mínima de 1 segundo entre llamadas.
ERR-AI-02 Medio	La respuesta de OpenAI viene truncada o incompleta	• El parámetro max_tokens es demasiado bajo. • El texto enviado como contexto supera el límite del modelo. • El prompt no instruye a responder de forma compacta.	1. Aumentar el valor de max_tokens en el comando. 2. Recortar o dividir el texto de entrada en chunks si es muy largo. 3. Usar modelos con mayor ventana de contexto (ej: gpt-4-turbo). 4. Revisar el conteo estimado de tokens antes de enviar.	Diseñar prompts compactos y establecer max_tokens acorde a la respuesta esperada. Para JSON estructurado, 500 tokens suelen ser suficientes.
ERR-AI-03 Medio	La respuesta de la IA no tiene el formato JSON esperado	• El modelo no responde en JSON aunque se le solicite. • Hay texto adicional antes o después del bloque JSON. • El modelo agregó comillas o backticks alrededor del JSON.	1. Agregar al prompt: ‘Responde ÚNICAMENTE con un JSON válido, sin texto adicional, sin backticks’. 2. Agregar una limpieza de texto posterior (remover comillas o marcas del formato). 3. Usar una moon JSON Parse para validar. 4. Especificar el schema exacto con un ejemplo.	Incluir siempre un ejemplo del JSON esperado en el prompt y especificar que no se incluya ningún texto adicional.

Categoría 5 — Flujo y Lógica del Agente

Código y Severidad	Error / Problema	Causas probables	Solución paso a paso	Cómo prevenirlo
ERR-FLOW-01 Medio	El agente termina sin ejecutar todas las moons esperadas	• Una condición If/Else redirige el flujo a un End anticipado. • Una variable nula o vacía hace fallar una condición. • El flujo no está correctamente conectado (moons sueltas).	1. Agregar moons de Log antes y después de cada If/Else. 2. Verificar en el diagrama que todas las moons estén encadenadas. 3. Revisar las condiciones con valores reales del log. 4. Agregar valores por defecto a variables nulas.	Siempre hacer clic derecho → Ejecutar robot con datos de prueba reales antes de pasar a producción.
ERR-FLOW-02 Alto	El agente procesa el mismo registro varias veces	• El trigger del agente se ejecuta más de una vez para el mismo evento. • No hay mecanismo de deduplicación en el flujo. • Un webhook está siendo reintentado por el proveedor.	1. Guardar el ID del evento en la base de datos al procesarlo. 2. Al inicio del flujo, verificar si el ID ya existe en la tabla. 3. Si existe, terminar el flujo de inmediato sin procesar. 4. Revisar la configuración de reintentos externa.	Todo agente que procese eventos externos debe tener deduplicación. Crear una tabla ‘eventos_procesados’ con el ID y la fecha.
ERR-FLOW-03 Medio	Las variables tienen valores de ejecuciones anteriores	• Las variables no se reinician al iniciar la ejecución. • Se reutiliza una variable global modificada por otra ejecución paralela.	1. Agregar una moon al inicio que asigne valores iniciales a las variables críticas. 2. Definir como variables locales (no globales) las que deban ser frescas. 3. Revisar si hay interferencia por ejecuciones paralelas.	Inicializar siempre las variables críticas al comienzo de cada flujo. No asumir que estarán vacías.

Categoría 6 — Conectores específicos frecuentes

Código y Severidad	Conector / Canal	Causas probables	Solución paso a paso	Cómo prevenirlo
ERR-CONN-01 Alto	Notion	• La página o base de datos no fue compartida con la integración. • El Integration Token fue revocado o regenerado en Notion.	1. Abrir la página o BD en Notion. 2. Hacer clic en los tres puntos (•••) arriba a la derecha. 3. Seleccionar ‘Add connections’ y elegir Saturn Studio. 4. Verificar que el Token coincida.	Cada nueva página o base de datos en Notion debe compartirse manualmente con la integración. No se comparte automáticamente.
ERR-CONN-02 Alto	WhatsApp (Evolution API)	• La sesión de WhatsApp Web venció. • El servidor de Evolution API no está accesible desde internet. • La instancia fue eliminada del servidor.	1. Usar el comando ‘Get QR Code’ para obtener uno nuevo. 2. Escanearlo desde el celular (Dispositivos vinculados). 3. Verificar que el servidor tenga IP pública y puerto 8080 abierto. 4. Si persiste, recrear la instancia.	Mantener el servidor de Evolution API siempre encendido. Las sesiones de WhatsApp Web se desconectan si el servidor no responde.
ERR-CONN-03 Alto	Mercado Libre / Pago	• El token OAuth venció (vigencia limitada). • El Redirect URI no coincide con https://studio.rocketbot.com. • Los scopes de la app no incluyen la operación.	1. Re-autenticar la credencial (eliminar y recrear en Saturn Studio). 2. Verificar el Redirect URI en el portal de desarrolladores (sin barra final). 3. Revisar y añadir los scopes necesarios. 4. Guardar y esperar unos minutos.	Los tokens OAuth tienen expiración. Implementar un mecanismo de renovación o re-autenticar periódicamente.

Checklists de diagnóstico rápido

Checklist 1 — Credencial que no conecta

• Abrí la credencial en Saturn Studio e hice clic en Check.
• Leí el mensaje de error exacto que aparece.
• Copié la API Key nuevamente desde la plataforma de origen (sin espacios).
• Verifiqué que la cuenta del servicio tiene el plan que soporta API.
• Para OAuth: verifiqué que el Redirect URI es exactamente https://studio.rocketbot.com
• Para OAuth: verifiqué que los scopes/permisos están configurados correctamente.
• Esperé 5 minutos y volví a intentar (algunos cambios tardan en propagarse).

Checklist 2 — Agente que falla al ejecutarse

• Abrí el panel de Log y leí el mensaje de error completo.
• Identifiqué cuál moon falló (aparece en rojo en el diagrama).
• Usé clic derecho → Ejecutar solo ese comando para aislar el problema.
• Verifiqué que la credencial usada en esa moon está conectada.
• Revisé si hay variables nulas o con valores inesperados antes de esa moon.
• Agregué moons de Log antes y después de la moon fallida para ver los valores.
• Consulté la categoría de error correspondiente en esta guía.

Checklist 3 — Base de datos que no conecta

• El servidor tiene IP pública (NO uso localhost ni 127.0.0.1).
• El puerto está abierto: 3306 (MySQL), 5432 (PostgreSQL), 1433 (SQL Server).
• El usuario tiene permisos para conectarse desde IPs externas.
• El nombre de la base de datos es exactamente el correcto (sensible a mayúsculas).
• Usé el botón Test Connection antes de guardar la credencial.
• Revisé los logs del servidor de base de datos para errores de conexión rechazada.

Checklist 4 — Webhook que no dispara el agente

• Copié la URL del webhook desde el panel de Webhooks en Saturn Studio.
• Pegué la URL correctamente en la plataforma externa (sin espacios adicionales).
• El método HTTP configurado coincide con el que usa el proveedor.
• Revisé el panel de monitoreo de Webhooks para ver si los eventos están llegando.
• Hice clic en el ojo azul de un evento para ver el raw data recibido.
• El Response Mode está configurado como Immediately para proveedores con timeout corto.
• La variable de destino (Assign result to Variable) está configurada.

Recursos de soporte

Recurso	Dónde	Para qué sirve
Documentación oficial	docs.rocketbot.co	Documentación completa de todos los módulos y conectores.
Foro de la comunidad	forum.rocketbot.com	Preguntas y respuestas de la comunidad de usuarios Saturn Studio.
Soporte conversacional	Slack (incluido con licencia)	Canal de soporte en tiempo real con el equipo de Rocketbot.
Academy	academy.rocketbot.com	Cursos gratuitos y certificaciones técnicas, disponibles en español.
Panel de Webhooks	Saturn Studio → Webhooks	Monitoreo en tiempo real de eventos recibidos y raw data para debugging.

Consejo: Al escalar a soporte — Incluir siempre: nombre del agente, screenshot del log de error, módulo/conector involucrado y los pasos que ya se intentaron. Esto reduce el tiempo de resolución significativamente.