> ## Documentation Index
> Fetch the complete documentation index at: https://omniloy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Info>
  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](/sofia/es/sdk/troubleshooting).
</Info>

## 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](https://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](/sofia/es/sdk/templates#checklist-de-validacion-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       |

<Info>
  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.
</Info>

## 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](/sofia/es/sdk/migration) para cómo actualizar cada prop deprecada.