Referencia de Errores

Referencia completa de códigos de error, mensajes y pasos de resolución del SDK de SofIA

Esta página documenta cada error que el SDK de SofIA puede emitir, organizado por categoría. Todos los errores se registran en la consola del navegador con el prefijo [Sofia SDK] cuando debug="true" está habilitado.

Para solución de problemas basada en síntomas (por ejemplo, “el componente no se carga”), consulta la guía de Solución de Problemas.

​

Categorías de error

El SDK clasifica los errores en siete categorías, cada una con un método de logger dedicado:

Categoría	Prefijo	Disparador
config	[Sofia SDK] Configuration Error	Props faltantes o inválidas, el componente no se monta
auth	[Sofia SDK] Authentication Error	API key inválida, token expirado (HTTP 401)
api	[Sofia SDK] API Error	Fallos de red, errores del servidor, fallos de generación de reportes
settings	[Sofia SDK] Settings Error	Fallos de parsing de template, errores al obtener configuración
audio	[Sofia SDK] Audio Error	Acceso al micrófono denegado, fallos de grabación de audio
storage	[Sofia SDK] Storage Error	LocalStorage no disponible, fallos de encriptación
webSocket	[Sofia SDK] WebSocket Error	Fallos de conexión, desconexiones durante transcripción

​

Errores de configuración

​

Propiedades requeridas faltantes

Salida en consola:

[Sofia SDK] Configuration Error - Missing or invalid required properties:

  • apikey: API key for authentication
  • userid: Unique identifier of the healthcare professional
  • patientid: Unique identifier of the patient
  • baseurl: API base URL (only required for keys that need it)
    Current value: "undefined"

Component will not mount until all required properties are provided.
Documentation: https://omniloy.mintlify.app/es/sdk/required-properties

Causa: Una o más de las props requeridas (apikey, userid, patientid) falta o está vacía — o, para una clave que lo requiere, falta baseurl.

Resolución:

1. Verificar que apikey, userid y patientid están configuradas en el elemento <sofia-sdk>
2. Comprobar que los valores no son strings vacíos ni undefined
3. Para las claves más nuevas el endpoint se resuelve automáticamente; si tu clave requiere baseurl, asegúrate de que esté configurada y use https://

​

Identificadores de sesión faltantes

Salida en consola:

[Sofia SDK] Session Warning - Missing session identifiers:

  • userid: Unique identifier of the healthcare professional
  • patientid: Unique identifier of the patient
    Current value: "undefined"

Component will not mount without session identifiers.

Causa: userid o patientid falta o está vacío.

Resolución:

1. Proporcionar tanto userid como patientid como strings no vacíos
2. Estos valores deben identificar de forma única la sesión actual de doctor y paciente

​

Errores de autenticación

​

API key inválida (HTTP 401)

Salida en consola:

[Sofia SDK] Authentication Error - Invalid API key provided. Please verify your API key is correct.

Causa: La prop apikey contiene una API key inválida, expirada o revocada.

Resolución:

1. Verificar que la API key es correcta y activa
2. Confirmar que estás usando la key correcta para tu entorno (sandbox vs producción)
3. Comprobar que la key no ha sido rotada o revocada
4. Contactar soporte si la key debería ser válida

​

URL base incorrecta (HTTP 404)

Salida en consola:

[Sofia SDK] Configuration Error - Base URL is incorrect. Please verify your baseurl property points to the correct API endpoint.

Causa: La prop baseurl apunta a un endpoint que no existe.

Resolución:

1. Verificar que la URL coincide con tu entorno asignado
2. Asegurar que no estás mezclando URLs de sandbox y producción
3. Revisar errores tipográficos en la URL

​

Errores de configuración (settings)

​

Validación de template fallida

Salida en consola:

[Sofia SDK] Settings Error - Template validation failed

Causa: La prop template contiene JSON inválido o le faltan claves requeridas del esquema ($schema, type, properties).

Resolución:

1. Validar la sintaxis JSON en jsonlint.com
2. Asegurar que el esquema incluye "$schema": "http://json-schema.org/draft-07/schema#"
3. Verificar que "type": "object" está presente
4. Comprobar que properties contiene al menos una definición de campo
5. Ver el Checklist de validación del template para más detalles

​

Fallback al template del servidor

Salida en consola:

[Sofia SDK] Settings Error - Using fallback template

Causa: La prop template local no pudo ser parseada después de tres intentos (JSON.parse, eliminación de prefijo, eval con Function). El SDK usa como respaldo el template configurado en el servidor para tu templateid.

Resolución:

1. Corregir el JSON del template local — esto suele ser un error de sintaxis
2. Verificar caracteres especiales no escapados en el string del template
3. Si se pasa programáticamente, asegurar que se pasa un string JSON, no un objeto JavaScript

​

Errores de API

​

Generación de reporte fallida

Salida en consola:

[Sofia SDK] API Error - Report generation failed: {detalles del error}

Causa: El proceso de generación de reportes encontró un error durante el procesamiento de IA.

Resolución:

1. Revisar el mensaje de error específico para obtener detalles
2. Verificar la conectividad de red al servidor API
3. Asegurar que el esquema del template es válido
4. Si el error persiste, reintentar después de unos segundos
5. Contactar soporte con el mensaje de error si el problema continúa

​

Errores de red

Salida en consola:

[Sofia SDK] API Error - {contexto}. Please contact support if this issue persists.

Causa: Errores HTTP 5xx o timeouts de red durante llamadas API.

Resolución:

1. Verificar la conectividad a internet
2. Comprobar si el endpoint API es accesible
3. Buscar errores CORS en la consola del navegador
4. Verificar que la configuración de firewall/proxy no bloquea el dominio de la API

​

Errores de audio

​

Acceso al micrófono denegado

Salida en consola:

[Sofia SDK] Audio Error - Microphone access denied

Causa: El permiso del micrófono del navegador fue denegado o la página no se sirve sobre HTTPS.

Resolución:

1. Verificar los permisos del navegador — clic en el icono de candado en la barra de direcciones
2. Asegurar que la página se sirve sobre HTTPS (requerido para WebRTC)
3. Verificar que el hardware del micrófono está conectado y funcional
4. En Chrome, ir a chrome://settings/content/microphone para verificar los permisos del sitio

​

Fallo de grabación de audio

Salida en consola:

[Sofia SDK] Audio Error - {detalles del error de grabación}

Causa: La grabación de audio falló por problemas de hardware, códecs o incompatibilidad del navegador.

Resolución:

1. Probar un micrófono diferente
2. Cerrar otras aplicaciones que puedan estar usando el micrófono
3. Probar en un navegador diferente (Chrome es recomendado)
4. Revisar la consola del navegador para errores WebRTC más específicos

​

Errores de WebSocket

​

Fallo de conexión

Salida en consola:

[Sofia SDK] WebSocket Error - {error de conexión}

Causa: La conexión WebSocket al servidor de transcripción falló o fue rechazada. La URL del transcriptor la proporciona automáticamente la API de settings (la prop wssurl está deprecada e ignorada desde v1.0.7).

Resolución:

1. Verificar la conectividad de red y las reglas de firewall
2. Asegurar que las conexiones WebSocket (wss://) no están bloqueadas por proxy
3. Confirmar que tu apikey es válida para que la API de settings pueda devolver la URL del transcriptor
4. Verificar que la página se sirve sobre HTTPS

​

Desconexión durante transcripción

Salida en consola:

[Sofia SDK] WebSocket Error - {detalles de desconexión}

Causa: La conexión WebSocket se cortó durante una transcripción activa.

Resolución:

1. Verificar la estabilidad de la red
2. El SDK intenta reconexión automática — esperar a que se reconecte
3. Si las desconexiones son frecuentes, revisar la infraestructura de red
4. Verificar que ningún proxy o firewall está terminando conexiones WebSocket inactivas

​

Errores de almacenamiento

​

LocalStorage no disponible

Salida en consola:

[Sofia SDK] Storage Error - {error de almacenamiento}

Causa: El LocalStorage del navegador no está disponible (modo de navegación privada, almacenamiento lleno o deshabilitado por política).

Resolución:

1. Verificar si el navegador está en modo privado/incógnito — algunas funciones pueden no persistir
2. Limpiar el almacenamiento del navegador si está lleno
3. Verificar que el LocalStorage no está bloqueado por políticas empresariales o configuración del navegador

​

Errores de validación de entrada

Estos errores ocurren cuando la entrada del usuario falla la validación de seguridad:

Mensaje de error	Causa
Input exceeds maximum length of {n} characters	El texto de entrada es demasiado largo
Input contains only whitespace	Entrada vacía o solo espacios en blanco
URLs not allowed in input	La entrada contiene URLs (bloqueadas por defecto)
Potentially malicious HTML/JavaScript content detected	Patrones XSS detectados
Potentially malicious SQL content detected	Patrones de inyección SQL detectados
Potentially malicious NoSQL content detected	Patrones de inyección NoSQL detectados
Invalid JSON format	JSON malformado en un campo que espera JSON

La validación de entrada se ejecuta automáticamente sobre la entrada del usuario. Estos errores son funciones de seguridad y no deben suprimirse. Si texto médico legítimo dispara un falso positivo, contacta soporte con el texto específico que fue rechazado.

​

Warnings de deprecación

Al usar props deprecadas con debug="true", el SDK emite:

[Sofia SDK] DEPRECATED: "{propName}" prop is deprecated and has no effect. {mensaje de migración} This prop will be removed in v2.0.

Consulta la Guía de Migración para cómo actualizar cada prop deprecada.