# Trampas conocidas

Lo que de verdad se han encontrado quienes integran, con el síntoma que ves primero. Tu agente de código recibe la misma lista en la skill (`references/pitfalls.md`). Avisa a Neurologyca si encuentras una nueva.

## En el dispositivo y el SDK

### `npm install` responde 404 para `@neurologyca/*`

**Síntoma.** `npm install` falla con `404 Not Found` (o `401`) para `@neurologyca/capture` o `@neurologyca/capture-server`.

**Causa.** Los paquetes están en el registro privado de Neurologyca: sin el `.npmrc` del proyecto, o sin `NODE_AUTH_TOKEN` en el entorno, npm los busca en el registro público.

**Qué hacer.** Añade el `.npmrc` de la página de instalación (los starters lo traen) y exporta `NODE_AUTH_TOKEN` con el token del registro que te dio Neurologyca. No es tu API key: no los confundas.

Afecta a: todas las versiones publicadas del SDK.

Más: [Instalación](/docs/es/start/install/)

### Measurement sin `taxonomy.contextId`

**Síntoma.** Crear el cliente con una configuración de Measurement lanza `taxonomy.contextId is required`, o `buildTenantKit` (`admin.buildTenantKit`) en tu backend rechaza Measurement con `E_KIT_NO_CONTEXT` y la inscripción que hiciste justo antes queda sin captura.

**Causa.** La configuración del SDK exige un id de contexto, y Measurement no se interpreta, así que su grupo no tiene contexto de interpretación. `buildTenantKit` de `capture-server` 0.19.0 y anteriores solo mira ese id y lanza; desde la 0.20.0 lee `interpreted` del catálogo de Engine y da a Measurement su propio kit (`kind: 'measurement'`), pero contra un Engine cuyo catálogo no publica `interpreted` sigue lanzando.

**Qué hacer.** Usa `taxonomy: { contextId: 'measurement' }` (un valor de relleno, `MEASUREMENT_CONTEXT_ID` en `capture-server`: desde 0.29.0 el SDK no lo envía cuando Engine dice que el protocolo no se interpreta) y pasa `triggerAnalysis: false` a la captura. El kit de Measurement de la consola lleva los dos en su `neuro.config.json` (Tu integración › Protocolos › un protocolo › Kit). En tu backend, usa `capture-server` 0.20.0 o posterior y ramifica por `kit.kind`: `'measurement'` trae esa configuración y un aviso de capturar con `triggerAnalysis: false`. Resuelve el kit antes de `admin.enrol`, así un kit que falle no deja una inscripción huérfana. `ProtocolSummary.interpreted` (`listProtocolLibrary`) dice si un protocolo se interpreta. Si `buildTenantKit` sigue lanzando `E_KIT_NO_CONTEXT` con Measurement (un `capture-server` anterior, o un Engine sin `interpreted`), usa la configuración fija de arriba.

Afecta a: todas las versiones publicadas del SDK (contextId) · capture-server 0.19.0 y anteriores, o un Engine sin interpreted (buildTenantKit).

Más: [Solo medir](/docs/es/guides/measurement/) · [Tu backend](/docs/es/sdk/backend/)

### Una fuente `<video>` que no da frames o acaba antes el plan

**Síntoma.** Con `{ type: 'video', el }` la captura no recibe frames, pierde el principio del fichero, o llega `source.ended` con steps pendientes y un step posterior falla. Desde la 0.43.0 una segunda captura sobre el mismo fichero puede fallar en el acto con `CaptureStartError` (`stage: 'source'`, «the capture source has already ended…»).

**Causa.** El SDK espera los metadatos del vídeo, así que el `src` va antes de `captureProtocol`; solo hay frames mientras el vídeo se reproduce; y cuando el fichero acaba no se puede capturar ningún step más. Desde la 0.43.0 (kodec 5.0.0-rc.14), un `<video>` que ya acabó cuando empieza la captura falla antes de cargar ningún modelo.

**Qué hacer.** Pon el `src` antes de `captureProtocol`, deja el elemento `muted` y `playsInline`, y llama a `play()` en `onStarted`. Con varios steps sobre un fichero, pon `loop` mientras dura el plan; con `source.ended` y steps pendientes, llama a `session.abort()`. Si el elemento ya llegó al final, rebobínalo (`currentTime = 0`) antes de `captureProtocol`.

Afecta a: SDK >=0.27.0.

Más: [En el dispositivo (tiempo real)](/docs/es/sdk/on-device/)

### La pestaña quedó oculta durante la captura

**Síntoma.** La serie tiene huecos reales y `onWarning` recibe `capture.throttled`. Ese aviso es relativo a la propia sesión: no es la señal de lo rápido que es el dispositivo.

**Causa.** Con la pestaña oculta o la ventana tapada, el navegador deja de procesar frames; el SDK solo avisa.

**Qué hacer.** Pide a la persona que deje la pestaña a la vista mientras captura y enseña el aviso.

Afecta a: todas las versiones publicadas del SDK.

Más: [Errores, avisos y reintentos](/docs/es/sdk/errors/) · [Cómo capturar para la máxima precisión](/docs/es/concepts/capture/)

### La cámara no se abre fuera de un contexto seguro

**Síntoma.** En un móvil u otra máquina de tu red la cámara no se abre nunca; `classifyMediaError` dice `insecure-context`.

**Causa.** Los navegadores solo dan la cámara a contextos seguros: HTTPS, o `localhost` en la misma máquina. Una dirección `http://` de tu red no lo es.

**Qué hacer.** Sirve la página por HTTPS (un túnel a tu máquina de desarrollo o un certificado para tu red local) y traduce los errores de medios con `classifyMediaError` para decirle a la persona qué hacer.

Afecta a: todas las versiones publicadas del SDK.

Más: [En el dispositivo (tiempo real)](/docs/es/sdk/on-device/)

### Funciona en local y falla en producción: la CSP

**Síntoma.** En producción la cámara no llega a estar lista, o se pierde la transcripción entera: `codec.error` con `audio-start-failed`, el aviso `stt` y `transcription: null` en el informe (`workerBlockedByCsp` no dice nada aquí: va dentro de `transcription`, que es `null`, y solo cubre el worker de voz).

**Causa.** Por defecto, Capture carga su motor de visión y sus modelos de CDN públicos, y su procesado de audio desde un `blob:`. Una Content Security Policy que no los permite los bloquea.

**Qué hacer.** Usa la política probada de la guía de CSP: `'wasm-unsafe-eval'` y `blob:` en `script-src`, `blob:` en `worker-src` y los orígenes de los CDN en `connect-src`; o aloja tú los ficheros (`kodec.*` y `transcribe.selfHost`).

Afecta a: todas las versiones publicadas del SDK.

Más: [CSP y transcripción](/docs/es/guides/csp-transcription/)

### El transcrito vuelve en inglés

**Síntoma.** El texto es fluido y bien puntuado, pero traducido al inglés; `onWarning` recibe `stt.autodetect`.

**Causa.** Con `language: null` el idioma se detecta del audio, lo que no es fiable con respuestas cortas: el modelo puede devolver una traducción sin ningún error.

**Qué hacer.** Fija el idioma con un código sin región: `transcribe: { language: 'es' }`. Sin `language`, el SDK usa el idioma de la página (`<html lang>`, y si no, el del navegador): una plantilla con `<html lang="en">` transcribe en inglés sin ningún aviso, así que fíjalo.

Afecta a: todas las versiones publicadas del SDK.

Más: [CSP y transcripción](/docs/es/guides/csp-transcription/)

### Levantar el veto de transcripción de forma automática

**Síntoma.** La transcripción no arranca (un aviso `stt` con `blocker: 'video-cost-veto'`) o, tras levantarlo por código, el vídeo se sigue congelando en ese dispositivo.

**Causa.** El veto es una medida real: transcribir hizo demasiado lenta la cámara en ese dispositivo, o su latencia demasiado alta (`reason: 'latency'`, con el vídeo intacto). `forgetTranscriptionVeto` la borra; llamarlo al arrancar o en un reintento convierte el veto en un bucle que pierde vídeo.

**Qué hacer.** Llama a `forgetTranscriptionVeto(kodec)` solo detrás de un botón que pulse la persona. Los indicadores se capturan igual.

Afecta a: todas las versiones publicadas del SDK.

Más: [CSP y transcripción](/docs/es/guides/csp-transcription/) · [Errores, avisos y reintentos](/docs/es/sdk/errors/)

### Una opción que el SDK no tiene

**Síntoma.** `createProtocolClient`, `captureProtocol`, un step o `createRecordingClient` lanzan `E_UNKNOWN_OPTION` antes de tocar la cámara; tras subir a la 0.42.0, un cliente que antes se creaba ahora lanza al crearse.

**Causa.** El SDK rechaza cualquier opción que no conoce. Desde la 0.42.0 eso incluye `createProtocolClient` (y cada clave dentro de `startup`), que antes ignoraba en silencio una clave desconocida; una opción de cada captura (como `signal` o `captureId`) pasada al cliente también se rechaza, y el mensaje dice que va en `captureProtocol`.

**Qué hacer.** Toma los nombres de las opciones solo de la referencia, nunca de memoria ni de ejemplos antiguos, y quita de la configuración cualquier clave de más. `triggerAnalysis`, `signal` y `captureId` van por captura, en `captureProtocol`.

Afecta a: todas las versiones publicadas del SDK.

Más: [Errores, avisos y reintentos](/docs/es/sdk/errors/) · [Referencia del SDK](/docs/es/sdk/reference/)

### Preparaste, y la captura lo vuelve a descargar todo

**Síntoma.** `prepare()` resolvió `ready`, pero al pulsar Empezar la cara (y la voz) se cargan otra vez: las etapas del arranque dicen `source: 'network'`, la espera es la misma y la página tiene los modelos dos veces.

**Causa.** Solo la siguiente captura del **mismo cliente** adopta lo que cargó `prepare()`. Un segundo cliente (uno creado en cada render o en cada componente, o uno para preparar y otro para capturar) no tiene nada que adoptar; `prepareCapture()` y `level: 'cache'` solo calientan la caché del navegador, y solo si la captura pide los mismos ficheros. Dos pestañas de tu app son dos páginas: cada una carga sus propios modelos, y solo comparten la caché del navegador.

**Qué hacer.** Crea un cliente por página y mantenlo toda la visita: prepara con él al montar la página, captura con él y llama a `client.release()` cuando la página o la vista se van. Con `prepareCapture()` en una página anterior, comparte el mismo objeto de configuración con la página de la captura. Con `keepPrepared: true` (0.43.0) usa ese mismo cliente en todas las capturas: cada una adopta lo que dejó la anterior, sin ningún `prepare()` entre medias, y llama a `client.release()` entre una persona y la siguiente en un dispositivo compartido. Sin la opción, la voz se libera tras cada sesión, así que prepara otra vez antes de la siguiente captura.

Afecta a: SDK 0.42.0 y posteriores.

Más: [En el dispositivo (tiempo real)](/docs/es/sdk/on-device/)

### Con `keepPrepared`, la siguiente persona hereda el modelo de la cara

**Síntoma.** En un dispositivo que pasa de una persona a otra (un quiosco, una tableta compartida), las capturas siguen usando los mismos modelos cargados de una persona a la siguiente, sin `prepare()` ni descarga nueva.

**Causa.** Con `keepPrepared: true` el cliente guarda los modelos de una captura a la siguiente hasta `client.release()` o hasta que la página se va. Son modelos, no lo capturado, pero el modelo de la cara puede arrastrar estado del último frame de una captura a la siguiente.

**Qué hacer.** Llama a `client.release()` entre una persona y la siguiente, o no enciendas la opción donde un dispositivo sirve a varias personas.

Afecta a: SDK 0.43.0 y posteriores.

Más: [En el dispositivo (tiempo real)](/docs/es/sdk/on-device/) · [Cargar los modelos](/docs/es/guides/load-models/)

### Sin WebGPU, preparar la voz entre capturas recarga la cara cada vez

**Síntoma.** Con `keepPrepared`, cada captura arranca tan despacio como la primera, y cada `prepare()` entre capturas da el aviso `prepare.released` con `'replaced'`.

**Causa.** Donde se rechaza la transcripción (sin WebGPU y sin `allowWasmWorker`) el modelo de voz nunca se guarda, así que un `prepare({ models: { face: true, speech: true } })` entre capturas pide algo que no está guardado: suelta la cara guardada y la vuelve a cargar.

**Qué hacer.** Prepara una vez antes de la primera captura y no prepares entre capturas, o pide solo la cara.

Afecta a: SDK 0.43.0 y posteriores.

Más: [Cargar los modelos](/docs/es/guides/load-models/) · [En el dispositivo (tiempo real)](/docs/es/sdk/on-device/)

### La transcripción deja de funcionar tras la 0.42.0 con ONNX Runtime alojado por ti

**Síntoma.** Con `transcribe.selfHost.wasmPaths` como cadena, la captura sigue sin voz: el aviso `stt` con `subStage: 'stt-runtime'`, `reason: 'network'` y, en `cut`, `code: 'stt-runtime-missing'` con la `url` que falta; en `prepare()`, `partial` con `speech-error`.

**Causa.** Desde la 0.42.0, `wasmPaths` como cadena es un prefijo que tiene que acabar en `/`: kodec lo pone delante del nombre del fichero y comprueba, con un `HEAD`, el par de ONNX Runtime del ejecutor en que corre (`ort-wasm-simd-threaded.jspi.{mjs,wasm}` en WebGPU con JSPI, `ort-wasm-simd-threaded.{mjs,wasm}` en WASM y en Safari e iOS). Un 404 o 410 de cualquiera de los dos para la voz en el acto. Un host que solo sirve el par Asyncify antes funcionaba y ahora falla así.

**Qué hacer.** Acaba el prefijo en `/` y sirve bajo él los dos pares de `onnxruntime-web/dist/`, o pasa `wasmPaths` como objeto, `{ wasm, mjs }`, apuntando a los ficheros exactos (en Safari e iOS, la build simple).

Afecta a: SDK 0.42.0 y posteriores.

Más: [CSP y transcripción](/docs/es/guides/csp-transcription/)

### Una webcam pasada como `stream` le dice a la persona que revise el vídeo

**Síntoma.** Abres tú la cámara y la pasas como `stream`; si no se ve ninguna cara a tiempo, el arranque falla y `userMessage` dice «No se ve ninguna cara en el vídeo…» en vez de pedir a la persona que se ponga frente a la cámara.

**Causa.** Desde la 0.42.1 el SDK elige el mensaje del primer frame por la fuente: `first-frame.timeout` solo con la webcam que abre él, `first-frame.timeout-media` con cualquier `stream` o `<video>` tuyo. No distingue una cámara en directo de un stream grabado.

**Qué hacer.** Sustituye `first-frame.timeout-media` en `startup.messages` por la frase de la webcam (o por tu propio texto), o deja que el SDK abra la cámara.

Afecta a: SDK 0.42.1 y posteriores.

Más: [En el dispositivo (tiempo real)](/docs/es/sdk/on-device/) · [Errores, avisos y reintentos](/docs/es/sdk/errors/)

### Reintentar `/analyze` como regla general

**Síntoma.** Un manejador de reintentos vuelve a llamar a `/analyze` tras cualquier fallo de la interpretación, y los fallos se acumulan en vez de resolverse.

**Causa.** `E_AXES_MISSING` es el único caso en que reintentar es correcto: el análisis no llegó a generarse porque faltaba un eje (casi siempre frames sin `featuresMeta` de una fuente propia). Otros fallos, como una generación que se quedó sin tiempo, empeoran con más carga. Con el SDK 0.40.0 ese caso llega como `E_TAXONOMY_REJECTED`: Engine ya no manda el detalle por el que el SDK lo clasificaba.

**Qué hacer.** Decide por `code`, nunca con una regla común. Con `E_AXES_MISSING` (hoy, `E_TAXONOMY_REJECTED` con una fuente propia), corrige `featuresMeta` y pide la interpretación otra vez sin volver a capturar; los demás, no los reintentes en bucle.

Afecta a: todas las versiones publicadas del SDK.

Más: [Errores, avisos y reintentos](/docs/es/sdk/errors/)

### Avisos de duración que no pediste

**Síntoma.** Llegan `step.duration-below-min` o `step.duration-above-max` a `onWarning` aunque no cambiaste nada.

**Causa.** `stepDurations` vale `'warn'` por defecto: un step duró fuera del mínimo o del máximo que declara el catálogo. Engine no impone las duraciones.

**Qué hacer.** Enséñalos o fíltralos por `code` en `onWarning`; usa `stepDurations: 'enforce'` para rechazar ese step (`E_STEP_DURATION`) u `'off'` para apagar la comprobación.

Afecta a: todas las versiones publicadas del SDK.

Más: [Steps y marcado](/docs/es/sdk/steps/)

### Abortar después de `stop()` destruye una captura buena

**Síntoma.** Tras `stop()`, `onError` trae `E_RESULTS_TIMEOUT` o `E_INTERPRETATION_TIMEOUT` con `recoverable: false`, tu código llama a `abort()` y la captura se pierde.

**Causa.** Un `recoverable` distinto de `true` significa que la captura se perdió solo durante los steps. Tras `stop()`, Engine ya tiene la captura y la sigue procesando.

**Qué hacer.** Llama a `abort()` ante un error no recuperable solo mientras corren los steps. Tras `stop()`, guarda `userProtocolId` y `protocolMechanicId` fuera de la pestaña y lee los resultados más tarde (`client.retrieveResults` o tu backend).

Afecta a: todas las versiones publicadas del SDK.

Más: [Errores, avisos y reintentos](/docs/es/sdk/errors/)

### El cliente apunta directamente a Engine

**Síntoma.** Todas las peticiones responden `401` y `onWarning` recibe `token.missing`.

**Causa.** `baseUrl` es una dirección absoluta de otro origen y no hay `getToken`: ninguna petición lleva token.

**Qué hacer.** Apunta `baseUrl` al proxy de tu backend (por ejemplo `/engine`), que pone el token; pasa `getToken` solo si usas un proxy sin `capture-server`.

Afecta a: todas las versiones publicadas del SDK.

Más: [Tu backend](/docs/es/sdk/backend/) · [Proxy a mano](/docs/es/api/proxy/)

### Un proxy hecho a mano al que le falta una ruta

**Síntoma.** Un `404` a mitad de captura, o en el baseline o la interpretación, mientras el resto funciona.

**Causa.** El SDK llama a 13 rutas, y algunas solo en algunos casos (baseline, cancelar, interpretación). Un proxy propio que no reenvía alguna responde `404`.

**Qué hacer.** Reenvía exactamente las 13 rutas de la página del proxy, o usa `createEngineProxy` de `capture-server`, que lleva la lista.

Afecta a: todas las versiones publicadas del SDK.

Más: [Proxy a mano](/docs/es/api/proxy/) · [Tu backend](/docs/es/sdk/backend/)

### `E_UPLOAD_FAILED` en una captura en vivo, leído como «sin reintentos»

**Síntoma.** Una captura en vivo termina con `E_UPLOAD_FAILED` enseguida, no tras los reintentos habituales; a menudo con un `413` de tu proxy.

**Causa.** `E_UPLOAD_FAILED` es un error del flujo en vivo (un lote parcial), no del diferido. Un 4xx (por ejemplo un `413` porque el lote supera el tope de cuerpo del proxy) es terminal al primer intento; solo un 5xx o un error de red se reintenta (3 intentos, 30 s).

**Qué hacer.** No lo leas como «sin reintentos» para reenviar a ciegas. Si es un `413`, sube el tope de cuerpo de tu proxy (al menos 4,5 MB con el SDK 0.34.0 o posterior, al menos 10 MB antes); una función serverless solo vale si su tope llega a eso (una función de Vercel, 4,5 MB, sí; una API route del Pages Router de Next.js (`pages/api`), 1 MB por defecto, no hasta que lo subas); si no, corrige la credencial o el receptor y vuelve a capturar cuando el par esté libre.

Afecta a: todas las versiones publicadas del SDK.

Más: [En el dispositivo (tiempo real)](/docs/es/sdk/on-device/) · [Errores, avisos y reintentos](/docs/es/sdk/errors/)

### El proxy detrás de un rewrite de Firebase Hosting (Cloud Run o Cloud Functions)

**Síntoma.** Con el proxy servido a través de Firebase Hosting, el flujo de eventos (`/stream`) o un `/analyze` largo se corta a los 60 s con un `504`; o el proxy rechaza todas las peticiones con `403` porque tu `authorize` no encuentra la cookie de sesión.

**Causa.** Firebase Hosting tiene un tiempo máximo de 60 segundos por petición, también cuando reescribe a Cloud Run o Cloud Functions con uno mayor, y el proxy mantiene abierto el flujo de eventos durante toda la captura. Hosting además quita las cookies de las peticiones que reenvía: solo llega a tu app la que se llama `__session`.

**Qué hacer.** Deja `/engine` fuera del rewrite de Hosting, para que nada corte el flujo a los 60 s, y sirve la página y el proxy en el mismo origen desde el runtime de larga vida (Cloud Run en su dominio, o detrás de un balanceador). Las peticiones que no pasan por Hosting conservan sus cookies, así que ahí tu cookie de sesión puede mantener su nombre: `__session` solo importa para lo que siga pasando por Hosting. Lo mejor, el proxy en el origen de la página. Si tiene que vivir en otro origen, desde `@neurologyca/capture` 0.45.0 hacen falta dos mitades: `credentials: 'include'` en el cliente (`createProtocolClient`, `createRecordingClient`, y `urlTokenProvider` si tu endpoint de token está ahí) y `cors: { origins: ['https://app.ejemplo.com'], credentials: true }` en `createEngineProxy` (`capture-server` 0.20.1 o posterior, que además expone `Retry-After`); sin la del cliente, tu cookie de sesión no llega a `authorize` y el proxy responde `403`. El navegador solo envía las cookies válidas para el host del proxy: en un subdominio del mismo sitio (la página en `app.ejemplo.com`, el proxy en `api.ejemplo.com`) dale a la cookie `Domain=ejemplo.com` (basta con `SameSite=Lax`); en otro sitio (por ejemplo, una dirección `*.run.app`) es una cookie de terceros (`SameSite=None; Secure`) que Safari bloquea por defecto, así que ahí sirve el proxy bajo tu propio dominio. Sin `getToken` detrás del proxy. Nunca te saltes la guarda: `cors.origins` admite orígenes exactos, nunca `"*"`.

Afecta a: todas las versiones publicadas del SDK, con Firebase Hosting.

Más: [Proxy a mano](/docs/es/api/proxy/) · [Tu backend](/docs/es/sdk/backend/)

### La consola se llena de mensajes de la librería de visión

**Síntoma.** Al arrancar la captura, la consola del navegador imprime líneas como `INFO: Created TensorFlow Lite XNNPACK delegate for CPU`, algunas como errores o avisos.

**Causa.** Vienen de MediaPipe (TensorFlow Lite), la librería de visión que carga el SDK. Escribe sus registros en la consola por el flujo de errores y el navegador los pinta en rojo. No son fallos de tu integración ni del SDK.

**Qué hacer.** Ignóralos. Decide que una captura falló por lo que informa el SDK (`onError`, `onWarning` y el `CaptureOutcome`), no por la consola. No ocultes esos mensajes con un filtro en el código de producción.

Afecta a: todas las versiones publicadas del SDK.

Más: [Errores, avisos y reintentos](/docs/es/sdk/errors/)

### Sin voz en un dispositivo sin WebGPU

**Síntoma.** En algunos móviles y ordenadores la captura mide la cara pero no transcribe nada: llega el aviso `stt` con `blocker: 'no-webgpu'` y la comprobación `webgpu-adapter` del diagnóstico del dispositivo (solo sale cuando se pide la voz) no pasa.

**Causa.** Transcribir en el dispositivo necesita un adaptador WebGPU utilizable (un navegador puede tener WebGPU y no ofrecer ninguno). Sin él, el SDK rechaza la transcripción salvo que pongas `transcribe.allowWasmWorker: true`, que deja al dispositivo probar el modelo de voz en WebAssembly, más despacio y solo en su propio Worker. La captura de los indicadores sigue igual.

**Qué hacer.** Si habrá voz solo se sabe al preparar la voz o al empezar a transcribir: una comprobación sin modelos no lo dice. Para saberlo antes de medir, pide la voz: sin adaptador WebGPU, `prepare({ models: { speech: true } })` da `webgpu-adapter` `fail` y no descarga la voz (con él, descarga los modelos). Enseña cada aviso `stt` y sigue sin voz; o pon `transcribe.allowWasmWorker: true` y acepta que el texto llega más tarde y que la primera carga de los pesos puede cerrar la pestaña en un dispositivo con poca memoria (si una Content-Security-Policy bloquea los workers, por esa vía tampoco hay voz). Si necesitas la voz en todos los dispositivos, el diferido (Preview, si tu organización lo tiene activado) la transcribe en el servidor.

Afecta a: todas las versiones publicadas del SDK.

Más: [Dispositivos, calidad y modo](/docs/es/start/devices-and-modes/) · [CSP y transcripción](/docs/es/guides/csp-transcription/) · [En el dispositivo (tiempo real)](/docs/es/sdk/on-device/)

### Las sesiones con el delegado de CPU pueden no compararse con las de GPU

**Síntoma.** `SessionReport.captureQuality.delegate` dice `'CPU'` en unos dispositivos y `'GPU'` en otros, y comparas sus sesiones como si fueran la misma medida.

**Causa.** La detección de la cara corre en la GPU (WebGL 2) y cae a la CPU cuando no se puede crear el delegado de GPU. Los dos delegados ejecutan los modelos con distinta precisión y distinto preprocesado de la imagen, así que los puntos de la cara no son idénticos entre uno y otro, y los resultados de sesiones con delegados distintos pueden no ser comparables. Lo que limita al dispositivo es esa detección en GPU, no la CPU: con solo la cara, el delegado de CPU no es necesariamente más lento.

**Qué hacer.** Guarda el `delegate` de cada sesión y compara sesiones con el mismo delegado. Comprueba que WebGL 2 funciona en los dispositivos a los que te diriges. No fijes `kodec: { delegate: 'CPU' }` salvo para diagnosticar un driver gráfico: fijar un delegado desactiva la caída, así que la captura falla en vez de degradarse.

Afecta a: todas las versiones publicadas del SDK.

Más: [Dispositivos, calidad y modo](/docs/es/start/devices-and-modes/) · [En el dispositivo (tiempo real)](/docs/es/sdk/on-device/)

### En iOS el micrófono mantiene su ganancia automática

**Síntoma.** En iPhone y iPad, los rasgos de la voz que dependen de la intensidad absoluta (energía, shimmer y la activación que sale de ellos) no cuadran con los de otros dispositivos, y la calidad de audio de kodec dice `agc: 'unknown'` y `trust: false`.

**Causa.** El SDK pide al micrófono `autoGainControl: false`, con la supresión de ruido y la cancelación de eco apagadas, para que la voz conserve su dinámica real. WebKit, que usan todos los navegadores de iOS, no implementa esa restricción: allí la ganancia automática no se puede apagar y el navegador no puede decir si está encendida (`'unknown'` no es «apagada»). El vídeo y los puntos de la cara no se ven afectados.

**Qué hacer.** No compares los rasgos de la voz basados en la intensidad entre iOS y otros dispositivos, ni entre sesiones con `trust` en `false`; guarda la plataforma con cada sesión. El navegador tampoco ve otras ganancias: los auriculares Bluetooth, las mejoras de micrófono de Windows o el aislamiento de voz de macOS e iOS.

Afecta a: todas las versiones publicadas del SDK.

Más: [Dispositivos, calidad y modo](/docs/es/start/devices-and-modes/) · [En el dispositivo (tiempo real)](/docs/es/sdk/on-device/)

### Ventanas privadas y almacenamiento bloqueado

**Síntoma.** En una ventana privada, o con el almacenamiento del sitio bloqueado: donde la voz correría en WebAssembly (sin WebGPU, o Safari e iOS) la transcripción se rechaza con `blocker: 'no-memory-to-learn'`; o, al grabar (diferido, Preview), llega el aviso `recording.storage-memory`.

**Causa.** Cuando el SDK no encuentra almacenamiento persistente (no distingue toda ventana privada: algunas guardan hasta cerrarse). En vivo, kodec no puede recordar lo que aprende en el dispositivo, como una configuración que cerró la pestaña, así que una carga que la mata se repetiría en cada sesión; ahí no arriesga la voz en WebAssembly (donde la voz corre en WebGPU sigue transcribiendo; no en Safari e iOS, donde corre en WebAssembly). Al grabar, no hay IndexedDB y la grabación vive solo en la memoria de la pestaña: si la pestaña se cierra antes de que acabe la subida, se pierde y no se puede reanudar.

**Qué hacer.** Pide una ventana normal cuando puedas. En vivo, sigue sin voz cuando se rechace. Al grabar con `recording.storage-memory` (y `upload.not-persistent` al empezar la subida), dile a la persona que no cierre la pestaña hasta que acabe la subida.

Afecta a: todas las versiones publicadas del SDK.

Más: [Dispositivos, calidad y modo](/docs/es/start/devices-and-modes/) · [CSP y transcripción](/docs/es/guides/csp-transcription/) · [Diferido (en servidor)](/docs/es/sdk/deferred/)

### Las sesiones largas en un móvil se ralentizan al calentarse

**Síntoma.** El ritmo de una sesión en un móvil baja según avanza, y la misma configuración da menos ritmo cuanto más tiempo lleva el móvil capturando.

**Causa.** El ritmo lo marca la detección de la cara en la GPU (WebGL 2), y un móvil se ralentiza cuando se calienta. Los primeros segundos tras el arranque tampoco son representativos: los modelos aún se están calentando.

**Qué hacer.** Trata una sesión larga en un móvil modesto como degradada, no estable, y plantea allí sesiones más cortas. Lee el ritmo que entrega el códec en ese dispositivo y en ese momento (el evento `capture-quality` y `captureQuality` del `SessionReport`) en vez de suponerlo por el modelo, y deja fuera los primeros segundos al describirlo.

Afecta a: todas las versiones publicadas del SDK.

Más: [Dispositivos, calidad y modo](/docs/es/start/devices-and-modes/)

### `minFps` no es el ritmo de la sesión

**Síntoma.** Lees `captureQuality.minFps` del `SessionReport` como el ritmo de la sesión, concluyes que el dispositivo no puede medir o comparas dispositivos por él.

**Causa.** `minFps` es la más baja de las ventanas de alrededor de un segundo que kodec mide en toda la sesión, arranque incluido (los modelos aún se están calentando) y cualquier momento con la pestaña oculta o la ventana tapada. La dispersión dentro de una sesión es mayor que casi cualquier diferencia que quieras leer en un solo número. 8 fps es el único suelo que publica el SDK. Por debajo, no estima el pulso (un canal opcional, apagado por defecto) y deja un veto de transcripción como provisional. No hay un umbral publicado de cómo afecta el ritmo a los indicadores: compara tus sesiones.

**Qué hacer.** Describe el ritmo con el evento `capture-quality`: la mediana de las ventanas tras el arranque, cuántas quedan bajo ese suelo y la más baja, sin la pestaña oculta (la página enlazada tiene el código). `delegate` es un dato para comparar y `droppedTotal` por encima de cero, un aviso aparte. Tampoco son el ritmo `capture.throttled`, relativo al ritmo de la propia sesión, ni `quality.warning`, de Engine.

Afecta a: todas las versiones publicadas del SDK.

Más: [Dispositivos, calidad y modo](/docs/es/start/devices-and-modes/) · [En el dispositivo (tiempo real)](/docs/es/sdk/on-device/)

### No decidas por el user-agent

**Síntoma.** Enciendes o apagas la voz, o eliges entre vivo y diferido, leyendo `navigator.userAgent`, y las versiones recientes de iOS pasan por otras más antiguas.

**Causa.** El user-agent no dice la versión de iOS: Safari en un iOS reciente se anuncia como una anterior y solo el token `Version/` dice la real. Por eso el informe de arranque lleva `uaVersionToken` junto a `userAgent`. El SDK no decide nada por el user-agent: su diagnóstico del dispositivo comprueba capacidades (el contexto seguro, el acceso a la cámara, la ruta de captura, WebGPU, WASM SIMD, el almacenamiento persistente).

**Qué hacer.** Decide por capacidades: llama a `prepare()` antes de medir y lee `PrepareResult.capture` y sus comprobaciones `device` (la página enlazada tiene el código). Usa `uaVersionToken`, no el user-agent, solo para agrupar informes al analizarlos; con `startup: { includeUserAgent: false }` los dos salen `null`.

Afecta a: @neurologyca/capture 0.42.0 y posteriores.

Más: [Dispositivos, calidad y modo](/docs/es/start/devices-and-modes/) · [Cargar los modelos](/docs/es/guides/load-models/)

### La transcripción ya no arranca en un navegador

**Síntoma.** La transcripción está encendida y el vídeo va bien, pero `/results` trae `speech` sin `transcript` en todas las capturas de ese navegador; `onWarning` recibe `stt` con `blocker: 'video-cost-veto'`, fácil de perder si tu UI solo guarda el último aviso.

**Causa.** Una captura anterior midió el vídeo por debajo de 8 fps (normalmente con la pestaña oculta) y guardó en el navegador un veto provisional. Debería caducar en cuanto una captura mida más de 8 fps, pero hasta 0.40.0 la transcripción arranca justo tras el primer frame, antes de que se mida la cadencia, así que el veto se respeta siempre.

**Qué hacer.** Actualiza `@neurologyca/capture` a 0.41.0 o posterior (fija kodec 5.0.0-rc.3): la primera captura que da vídeo por encima de 8 fps borra el veto provisional y transcribe; solo esa captura espera, hasta unos 3 s. 0.40.1 ya transcribía, pero conservaba el veto y esperaba en cada captura. El veto borrado se informa una vez, en `SessionReport.transcriptionSetup.provisionalVetoLifted`. Una captura que se queda en 8 fps o menos (una pestaña oculta, o un `fps` de captura de 8 o menos) lo conserva: mantén la pestaña a la vista y enseña todos los avisos.

Resuelta en 0.40.1: actualiza a esa versión.

Más: [CSP y transcripción](/docs/es/guides/csp-transcription/) · [Errores, avisos y reintentos](/docs/es/sdk/errors/)

### `createEngineAdmin` falla al cargarlo con `require()`

**Síntoma.** En un backend CommonJS (`require('@neurologyca/capture-server')`, o TypeScript compilado a CommonJS), cada llamada de administración que necesita un token de Engine falla con `ReferenceError: return_nullishCoalesce is not defined`.

**Causa.** De la 0.12.0 a la 0.17.0, la entrada CommonJS del paquete se generaba mal: la petición del token de `createEngineAdmin` (y de un `createHttp` usado directamente) llamaba a una función que no existe. La entrada de módulos ES (`import`) no estaba afectada.

**Qué hacer.** Actualiza tu backend a `capture-server` 0.17.1 o posterior. Sin cambios de código.

Resuelta en capture-server 0.17.1: actualiza a esa versión.

Más: [Instalación](/docs/es/start/install/)

### Un `413` de un proxy en una función de Vercel (u otro host con tope de 4,5 MB)

**Síntoma.** Una captura en vivo termina con `E_UPLOAD_FAILED` en su primer lote, y el proxy, alojado en una función de Vercel o en un host parecido, responde `413`.

**Causa.** Antes de 0.34.0 el SDK cortaba los lotes solo por número: hasta 300 frames, unos 9,3 MB con cámara. Eso supera el tope de cuerpo de una función de Vercel (4,5 MB) y el de una API route del Pages Router de Next.js (`pages/api`) por defecto (1 MB), y un 4xx termina la sesión al primer intento.

**Qué hacer.** Actualiza al SDK 0.34.0 o posterior: cada lote en vivo lleva como mucho 3 MB de frames, así que un proxy con un tope de cuerpo de al menos 4,5 MB lo admite. Esto no cubre una API route del Pages Router de Next.js (`pages/api`): su tope de 1 MB por defecto queda por debajo de un lote con cualquier versión del SDK, así que responde `413` hasta que subas su límite. Ese caso, y cómo leer el `E_UPLOAD_FAILED`, está en la trampa `upload-failed-4xx-terminal` (`E_UPLOAD_FAILED` leído como «sin reintentos»).

Resuelta en 0.34.0: actualiza a esa versión.

Más: [Proxy a mano](/docs/es/api/proxy/) · [Tu backend](/docs/es/sdk/backend/)

### `createEngineProxy` responde `413 E_BODY_TOO_LARGE` con su límite por defecto

**Síntoma.** Una captura en vivo termina con `E_UPLOAD_FAILED`, y el proxy de tu backend respondió `413` `E_BODY_TOO_LARGE` a un `POST /process-kpn-emo`.

**Causa.** Hasta `capture-server` 0.11.0, `createEngineProxy` leía cuerpos de hasta 8 MiB por defecto (`maxBodyBytes`), y un SDK anterior a 0.34.0 envía lotes de hasta unos 9,3 MB con cámara.

**Qué hacer.** Actualiza tu backend a `capture-server` 0.12.0 o posterior (por defecto 16 MiB) y el SDK a 0.34.0 o posterior, o pasa un `maxBodyBytes` mayor. Una petición puede tener ahora ese cuerpo en memoria, así que limita la concurrencia de tu servidor.

Resuelta en capture-server 0.12.0: actualiza a esa versión.

Más: [Tu backend](/docs/es/sdk/backend/) · [Errores, avisos y reintentos](/docs/es/sdk/errors/)

### Con webpack (Next.js), `init()` falla antes de abrir la cámara

**Síntoma.** La build pasa con el aviso «Critical dependency: the request of a dependency is an expression» y, en ejecución, la captura falla antes de abrir la cámara con «Cannot find module» para el bundle de MediaPipe.

**Causa.** kodec 4.2.1, el que traía el SDK antes de 0.34.0, carga MediaPipe con un `import()` dinámico que webpack sustituía por un módulo vacío. Vite y Rollup lo dejan tal cual, así que no les afectaba.

**Qué hacer.** Actualiza `@neurologyca/capture` a 0.34.0 o posterior: fija kodec 4.2.2 o posterior (0.36.5 fija kodec 5.0.0-rc.2), cuyo `import()` lleva `webpackIgnore`. kodec no es una dependencia que instales tú. Turbopack no está probado.

Resuelta en kodec 4.2.2: actualiza a esa versión.

Más: [Instalación](/docs/es/start/install/)

### Dos interpretaciones, y pagas las dos

**Síntoma.** Con el SDK en tiempo real y `triggerAnalysis` activo, la persona ve una interpretación en la página y `POST /analyze` desde tu backend devuelve otra, con `from_cache: true`.

**Causa.** El `Final` con `triggerAnalysis` hace que Engine genere y guarde una interpretación (la que avisa `constellation.complete`). Hasta el SDK 0.37, cuando `stop()` tenía los resultados y ese aviso aún no había llegado, el SDK abría además `/analyze/stream`, que siempre genera una nueva, no lee ninguna caché y no guarda nada. Dos generaciones del modelo de lenguaje, dos textos, las dos se cobraban. La válida es la guardada.

**Qué hacer.** Desde 0.38.0, `stop()` espera el aviso de Engine hasta `analyzeTimeoutMs` y, si no llega, llama una vez a `POST /analyze`, que sirve la guardada: una interpretación por sesión, el mismo texto que lee tu backend. Desde la 0.44.0, si ese `/analyze` responde `202 ANALYSIS_IN_PROGRESS`, el SDK espera y vuelve a pedirla dentro de `analyzeTimeoutMs` contado desde el primer `202`, y acaba con `E_ANALYSIS_IN_PROGRESS` si se agota. `stop()` puede tardar más (unos 13 minutos en el peor caso con los valores por defecto). `SessionReport.interpretationSource` dice de dónde salió; el aviso `analysis.regenerated` (`from_cache: false`) significa que `/analyze` tuvo que generarla. No pidas `interpretation: 'stream'` salvo que necesites progreso por fases: genera una que Engine no guarda. No llames tú además a `/analyze/stream`: cada llamada genera de nuevo.

Resuelta en 0.38.0: actualiza a esa versión.

Más: [HCIs y resultados](/docs/es/concepts/results/) · [Los resultados en tu backend](/docs/es/sdk/results-backend/)

## Diferido (en servidor) · Preview

### Llamar a `/analyze` una y otra vez tras un trabajo diferido

**Síntoma.** Cada lectura de la interpretación de un trabajo diferido tarda decenas de segundos (hasta unos dos minutos) y cuesta, o vuelve distinta.

**Causa.** Con `interpretation: 'ready'`, el análisis guardado sale de la caché. Con `'degraded'` o `'failed'` ninguna llamada lee el guardado: cada `/analyze` lo regenera (con sus tokens de LLM). Pedirlo antes del `succeeded` del trabajo también puede generar otro.

**Qué hacer.** Espera `succeeded` y lee su `interpretation`. Con `ready`, léela; con `degraded` o `failed`, pídela una vez si la necesitas, nunca en bucle. `timeout` no es un fallo: los indicadores están bien.

Afecta a: capture-server >=0.11.0.

Más: [Servicio de procesado](/docs/es/sdk/processing/)

### Tratar el aviso `interpreting` como un fallo

**Síntoma.** Con `interimWebhook: true`, los trabajos diferidos acaban en un `timeout` falso y sus vídeos no se borran nunca.

**Causa.** `interpreting` es un aviso, no un final: el trabajo sigue esperando la interpretación. Un `onEvent` que trata todo estado distinto de `succeeded` como fallo cierra el trabajo, y se deniega la renovación del token.

**Qué hacer.** Trata primero `interpreting`. Borra el vídeo en `interpreting` o en `succeeded`, lo que llegue antes; deja el trabajo abierto hasta `succeeded` y que un `interpreting` tardío no reabra nada. Actualiza el manejador antes de encender `interimWebhook`.

Afecta a: capture-server >=0.11.0.

Más: [Servicio de procesado](/docs/es/sdk/processing/)

### La subida está completa, pero el servicio de procesado no la recibe

**Síntoma.** Todos los bytes se suben, pero `uploadRecording` sigue reintentando `complete` (503 `E_NOTIFY_FAILED`, `Retry-After: 30`) durante minutos y luego rechaza con `E_UPLOAD_NOT_NOTIFIED`. Tu backend registra `E_UNAUTHORIZED` (o un error de red) de `submit`.

**Causa.** La grabación está guardada en tu backend; lo que falla es tu `onComplete`, que se la entrega al servicio de procesado: el servicio está caído, o no acepta tu key de servicio o el cliente dado de alta.

**Qué hacer.** No lo enseñes como una subida fallida: di que está subida y pendiente de entregar. Reintenta desde tu backend (`receiver.pendingNotifications()` y `receiver.notify()` cada minuto), registra el código del `ProcessorError` sin el cuerpo y revisa la key de servicio (`E_UNAUTHORIZED` es un error de configuración: reintentar no lo arregla).

Afecta a: capture 0.29.2 o posterior y capture-server 0.11.0 o posterior.

Más: [Diferido (en servidor)](/docs/es/sdk/deferred/) · [Servicio de procesado](/docs/es/sdk/processing/)

### Cancelar desde la página con la subida ya completa

**Síntoma.** Con la subida completa, `abandonUpload` (un `DELETE` a tu receptor) responde 409 `E_ALREADY_COMPLETE`; tu página dice que la grabación se descartó, pero tu backend conserva el trabajo, lo sigue reintentando y aún puede procesarlo.

**Causa.** Una subida completa es de tu backend: su dueño solo puede abandonar una sin terminar.

**Qué hacer.** Dale a tu página su propia ruta de cancelar en tu backend (con la sesión del usuario y solo su captura): cierra el trabajo como cancelado, deja de dar tokens para él, borra el vídeo con `receiver.remove()` (lanza `UploadBusyError` mientras corre el `onComplete` de esa captura: reinténtalo después) y haz que `onComplete` salte una captura ya cerrada. Di «descartada» solo cuando tu backend lo confirme.

Afecta a: capture-server 0.11.0 o posterior.

Más: [Diferido (en servidor)](/docs/es/sdk/deferred/) · [Servicio de procesado](/docs/es/sdk/processing/)

### Apuntar el servicio de procesado a localhost

**Síntoma.** Probando en tu máquina, los trabajos fallan con `E_DESTINATION_NOT_ALLOWED`, o el servicio nunca descarga el vídeo ni llama a tu webhook.

**Causa.** El servicio de procesado de Neurologyca solo llama a un origen `https:` público: rechaza `http:`, `localhost`, las direcciones privadas y de loopback, las redirecciones y las URLs con credenciales.

**Qué hacer.** Pon en `PUBLIC_BASE_URL` el origen HTTPS público de tu backend y construye con él la URL del vídeo, `tokenUrl` y `webhookUrl`. En tu máquina, abre un túnel HTTPS público (cloudflared o ngrok), pon su origen en `PUBLIC_BASE_URL` y ciérralo al terminar; o despliega. Después, `retry` de los trabajos fallidos: no es un reintento a ciegas.

Afecta a: El servicio de procesado de Neurologyca.

Más: [Servicio de procesado](/docs/es/sdk/processing/)

### Fiarse de la IP del servicio en vez de la firma

**Síntoma.** Tu URL del token o tu webhook se saltan la comprobación de la firma porque las tres rutas están limitadas a la IP de salida del servicio.

**Causa.** Esa IP es la misma para todas las organizaciones: otra puede hacer que el servicio llame a tus rutas desde ella. Limitar por IP es defensa en profundidad, no autenticación.

**Qué hacer.** Deja que `createWebhookHandler` y `createProcessorTokenHandler` verifiquen el HMAC con tu `PROCESSOR_SECRET`, y el receptor la firma de la URL del vídeo, limites por IP o no.

Afecta a: El servicio de procesado de Neurologyca.

Más: [Servicio de procesado](/docs/es/sdk/processing/)

### Mandar un trabajo sin sus parámetros

**Síntoma.** `submit` se rechaza con `400 E_BAD_REQUEST`, o con `400 E_JOB_PARAMS_CONFLICT`.

**Causa.** El servicio de Neurologyca tiene una credencial por organización para todos los protocolos, así que cada trabajo dice su contexto y su idioma: sin `taxonomy.contextId` o sin `language` responde `E_BAD_REQUEST`. Un procesador autoalojado cuyo cliente los fija rechaza otro valor con `E_JOB_PARAMS_CONFLICT`.

**Qué hacer.** Manda `taxonomy` (el `taxonomy.contextId` de la página), `language` (el de la sesión) y `transcribeSteps` en cada `submit`, con `capture-server` 0.13.0 o posterior. Con `E_JOB_PARAMS_CONFLICT`, manda los valores del cliente, o ninguno. No repitas la misma llamada.

Afecta a: capture-server >=0.13.0.

Más: [Servicio de procesado](/docs/es/sdk/processing/)

### El navegador no puede grabar MP4/H.264

**Síntoma.** La grabación se rechaza con `E_RECORDER_UNSUPPORTED` (`classifyMediaError` dice `recorder-unsupported`).

**Causa.** El modo diferido graba MP4 con vídeo H.264; algunos navegadores, como Firefox de escritorio, no pueden. Firefox no es objetivo: kodec no se ha probado allí.

**Qué hacer.** No hay reintento: ofrece otro navegador o el modo en el dispositivo.

Afecta a: todas las versiones publicadas del SDK.

Más: [Diferido (en servidor)](/docs/es/sdk/deferred/) · [Errores, avisos y reintentos](/docs/es/sdk/errors/)

### Un `capture-server` más antiguo que el servicio que espera

**Síntoma.** Mientras un trabajo espera su interpretación, cada `submit` y `getJob` falla con `E_PROCESSOR_PROTOCOL`, y el móvil sigue reintentando `complete` contra un `503`.

**Causa.** Un `capture-server` anterior a 0.11.0 no conoce el estado `interpreting` que el servicio de procesado comunica ahora, aunque `interimWebhook` esté apagado.

**Qué hacer.** Actualiza tu backend a `capture-server` 0.11.0 o posterior.

Resuelta en capture-server 0.11.0: actualiza a esa versión.

Más: [Servicio de procesado](/docs/es/sdk/processing/) · [Instalación](/docs/es/start/install/)

### Grabar un `<video>` con un SDK anterior a 0.27.2

**Síntoma.** El servicio de procesado rechaza una grabación de un `<video>` o de un stream (`E_MANIFEST_INVALID`), o Engine tarda varias veces más en procesarla.

**Causa.** 0.27.0 cerraba el último step después del final del fichero grabado, y 0.27.0 y 0.27.1 grababan un `<video>` a la frecuencia de la pantalla en vez de a 30 fps.

**Qué hacer.** Usa 0.27.2 o posterior, y vuelve a grabar lo que se grabó de un `<video>` con 0.27.0 o 0.27.1.

Resuelta en 0.27.2: actualiza a esa versión.

Más: [Diferido (en servidor)](/docs/es/sdk/deferred/)

## API HTTP

### Sin interpretación por HTTP: falta `triggerAnalysis`

**Síntoma.** Todos los lotes responden `202` y llegan los indicadores, pero `constellation.complete` nunca llega.

**Causa.** Por HTTP, un `triggerAnalysis` omitido significa que no se pide interpretación; el SDK hace lo contrario.

**Qué hacer.** En un protocolo interpretado, envía `triggerAnalysis: true` en el `Final` del último step, o llama a `POST /analyze` cuando los resultados estén listos.

Afecta a: API.

Más: [Guía de la API HTTP](/docs/es/api/) · [Límites declarados y modos de fallo](/docs/es/concepts/limits/)

### Un `Final` enviado justo después del lote anterior

**Síntoma.** El agregado del step no incluye los últimos lotes antes del `Final`.

**Causa.** Engine agrega el step cuando llega el `Final`, y el lote justo anterior puede seguir procesándose.

**Qué hacer.** Antes de cada `Final`, espera 2,5 s desde el lote anterior aceptado, como hace el SDK.

Afecta a: API.

Más: [Guía de la API HTTP](/docs/es/api/)

### Lotes que rompen el contrato del step

**Síntoma.** Los lotes responden `202` pero la posición no se completa, o no se pide la interpretación, o el `Final` responde `400`.

**Causa.** Cada step se numera por separado: `kpnfile.order` empieza en 1 en cada step, y cada step necesita su propio `Final`. `triggerAnalysis` solo cuenta en el `Final` del último step, y un lote necesita al menos un frame.

**Qué hacer.** Reinicia `kpnfile.order` en 1 en cada step, cierra cada step con un `Final` con frames, envía `triggerAnalysis` solo en el `Final` del último step y no pases de 300 frames o 3 MB de frames por lote como mucho, lo que llegue antes, como el SDK (en una mecánica de flujo libre, añade también ahí `mechanicComplete: true`).

Afecta a: API.

Más: [Guía de la API HTTP](/docs/es/api/) · [Límites declarados y modos de fallo](/docs/es/concepts/limits/)

### Un `Final` con lotes que faltan

**Síntoma.** El `Final` de un step responde `400` con `qualityCode: "KPN-EMO-MISSING-PACKETS"` y una lista `missingOrders`.

**Causa.** No llegaron lotes anteriores de ese step. Ese `Final` no guardó nada.

**Qué hacer.** Reenvía los lotes de `missingOrders` y después vuelve a enviar el `Final`.

Afecta a: API.

Más: [Límites declarados y modos de fallo](/docs/es/concepts/limits/) · [Referencia de la API](/docs/es/reference/)

### Leer un `400` de lote sin su `qualityCode`

**Síntoma.** Un lote responde `400` y reintentarlo no cambia nada.

**Causa.** Cuando un lote rompe el contrato, el cuerpo dice por qué en `qualityCode` (`KPN-EMO-…`). Solo algunos motivos se arreglan reenviando.

**Qué hacer.** Decide por `qualityCode` con la tabla de Límites: corrige el `step` con `KPN-EMO-STEP`, reenvía con `KPN-EMO-MISSING-PACKETS` y no reintentes el resto.

Afecta a: API.

Más: [Límites declarados y modos de fallo](/docs/es/concepts/limits/)

### Esperar `results.ready` tras cada step

**Síntoma.** Tu código espera un `results.ready` tras cada step, o uno con un `stepOrder` concreto, y se queda colgado o lee antes de tiempo.

**Causa.** `results.ready` llega una vez por posición, cuando su captura está completa, y no en todos los casos: en una posición que pidió la interpretación normalmente no llega (llega `constellation.complete`), y en casos raros llega dos veces. Su `stepOrder` no siempre es el del último step.

**Qué hacer.** Tómalo como señal, no como la verdad: sigue sondeando `GET /results/{userProtocolId}/{protocolMechanicId}` como respaldo hasta que tenga datos, e ignora su `stepOrder`.

Afecta a: API.

Más: [Guía de la API HTTP](/docs/es/api/) · [HCIs y resultados](/docs/es/concepts/results/)

### Culpar a los `taxonomyWarnings` de un fallo

**Síntoma.** `POST …/context` responde `201` con `taxonomyWarnings` (`UNKNOWN_CONTEXT`, `UNKNOWN_HCI`) justo con los ids que te da tu kit.

**Causa.** Engine comprueba los ids contra su copia local de la taxonomía. En el Engine del entorno de pruebas esa copia se refresca al arrancar y cada 6 horas, así que un aviso justo después de un cambio de taxonomía puede ser esa espera. Esos avisos no detienen el análisis.

**Qué hacer.** Lee la lista y regístrala, pero lo que confirma que el contexto funciona es que `POST /analyze` responda. La causa de un `422` está en otra parte.

Afecta a: API.

Más: [Guía de la API HTTP](/docs/es/api/)

### Filtros de bloquear o desbloquear enviados en el cuerpo

**Síntoma.** `POST /users/block` o `/users/unblock` actúa sobre todos los usuarios al alcance de la key en vez de sobre el que querías (antes del cambio de Engine del 2026-11-02 en el Engine de pruebas, que responde `400` a una llamada sin filtro o con cuerpo; el Engine de producción todavía lo hace).

**Causa.** Sus filtros (`externalId`, `role`, `developer`) se leen de la query. En el Engine de producción un cuerpo no se lee, y sin filtro la llamada se aplica a todos los usuarios a tu alcance; el Engine del entorno de pruebas responde `400` en su lugar, salvo que la llamada lleve `all=true`.

**Qué hacer.** Pon los filtros en la query (`?externalId=…`) y, en tu propio código, no envíes la llamada sin ninguno. Usa `all=true` solo a propósito, para actuar sobre todos los que alcanzas.

Afecta a: API.

Más: [Referencia de la API](/docs/es/reference/)

### Un proxy a mano que reenvía cualquier cosa, o deja pasar `reAnalyze`

**Síntoma.** El proxy funciona, pero una petición manipulada desde el navegador puede alcanzar rutas más allá de las 13 que el SDK necesita, o forzar una interpretación nueva.

**Causa.** El proxy es un pass-through con tu key de Engine en vez de una lista blanca. Todo lo que el navegador pueda enviar llega a Engine con tu key.

**Qué hacer.** Reenvía solo las 13 rutas y responde `404` a todo lo demás; quita `reAnalyze` de los cuerpos de `/analyze` y `/analyze/stream` para que una página no pueda forzar una reinterpretación de pago. `createEngineProxy` con `ownsAll` hace las dos cosas.

Afecta a: todas las versiones publicadas del SDK.

Más: [Proxy a mano](/docs/es/api/proxy/) · [HCIs y resultados](/docs/es/concepts/results/)

## Cualquier vía

### La API key llegó al navegador

**Síntoma.** Tu key `kop_…` aparece en un bundle, en `neuro.config.json`, en una variable de entorno pública o en una petición que hace la página.

**Causa.** Quien tenga la key puede acuñar tokens para toda tu organización. La key es solo de tu backend.

**Qué hacer.** Deja la key en el entorno de tu backend (`ENGINE_API_KEY`, nunca en git). Con el SDK, el proxy de tu backend pone el token y la página crea el cliente sin `getToken`; por HTTP, tu backend acuña el token. Si la key se filtró, pide rotarla.

Afecta a: todas las versiones publicadas del SDK · API.

Más: [Tu backend](/docs/es/sdk/backend/) · [Proxy a mano](/docs/es/api/proxy/)

### Un id de contexto que no sale de tu kit

**Síntoma.** `POST …/context` responde `201` (con `taxonomyWarnings`), la captura acaba bien y luego la interpretación se rechaza con un `422` (`E_TAXONOMY_REJECTED` en el SDK).

**Causa.** Engine no rechaza un id que no reconoce al fijar el contexto; la taxonomía queda fijada al capturar y solo la interpretación la comprueba.

**Qué hacer.** Toma el contexto, el subcontexto y las audiencias de tu kit (`neuro.config.json` y `KIT.md`), nunca los adivines. Si en `KIT.md` queda algo por resolver, pídeselo a Neurologyca antes de grabar a nadie.

Afecta a: todas las versiones publicadas del SDK · API.

Más: [Instalación](/docs/es/start/install/) · [Protocolos y su jerarquía](/docs/es/concepts/protocols/)

### La lectura está escrita para otra persona de la que la lee

**Síntoma.** `POST /analyze` responde `200` y la interpretación está completa, pero le habla a otro lector: una lectura escrita para la persona que enseñas a otra, o al revés. Sin `audience`, `audience_applied` llega `null`.

**Causa.** Sin `audience` (en la petición o en la persona), Engine aplica la lectura por defecto. Un contexto con varias audiencias puede tener una de por defecto, y no siempre es el lector que tienes en mente.

**Qué hacer.** Mira en `KIT.md`, en Audiencias, cuál va marcada como la de por defecto, si hay una. Si tu lector es otro, fíjala en la persona (`POST /users`, o después `PATCH /users/{externalId}`) o envíala en `POST /analyze`.

Afecta a: todas las versiones publicadas del SDK · API.

Más: [HCIs y resultados](/docs/es/concepts/results/) · [Tu kit](/docs/es/access/kit/)

### Pedir una interpretación a Measurement

**Síntoma.** Con Measurement, `POST /analyze` responde `409` con `PROTOCOL_NOT_ANALYSED`, o `client.analyze()` lo lanza, o tu página espera una interpretación que nunca llega.

**Causa.** Measurement no se interpreta nunca. Un `triggerAnalysis` omitido vale `true` en el SDK y `false` por HTTP. Desde el SDK 0.29.0 el SDK se salta el análisis solo cuando Engine devuelve `interpreted: false` (y avisa `protocol.not-interpreted`), pero no todo Engine devuelve aún ese campo.

**Qué hacer.** Pasa `triggerAnalysis: false` a `captureProtocol` con Measurement (el `neuro.config.json` del kit lo lleva para que tu código lo pase), no llames a `/analyze` para él y lee los indicadores con `GET /results/{userProtocolId}/{protocolMechanicId}`.

Afecta a: todas las versiones publicadas del SDK · API.

Más: [Solo medir](/docs/es/guides/measurement/) · [Errores, avisos y reintentos](/docs/es/sdk/errors/)

### Un baseline de otra persona o de otro origen

**Síntoma.** Los indicadores de una persona salen desplazados, aunque la captura fue bien.

**Causa.** El baseline es la expresión de reposo de una persona, y Engine lo aplica siempre que existe, aunque sea inválido. Un baseline capturado con otra persona o con otro origen (un vídeo de prueba, una muestra sintética) descuenta la expresión equivocada.

**Qué hacer.** Captura el baseline de la misma persona, con el mismo tipo de origen con el que vas a medir, con el `externalId` de esa persona. No reutilices una identidad de prueba para todos.

Afecta a: todas las versiones publicadas del SDK · API.

Más: [Baseline](/docs/es/concepts/baseline/)

### El baseline no está justo después de su Final

**Síntoma.** Justo después de aceptarse el último lote del baseline, `GET /users/{externalId}/baseline` responde `404` (o `getBaselineInfo` devuelve `null`).

**Causa.** Engine calcula el baseline en segundo plano tras el `Final`; tarda unos segundos. Para una persona sin ninguna captura previa, un `404` antes de eso es la respuesta esperada: aún no hay baseline. La consola del navegador lo pinta como un error en rojo; no lo es.

**Qué hacer.** Reléelo varias veces, con unos segundos entre lecturas, antes de dar por fallida la captura. Mira `missingOrders` en el último `202`: si faltan lotes, no se calcula ningún baseline.

Afecta a: todas las versiones publicadas del SDK · API.

Más: [Baseline](/docs/es/concepts/baseline/)

### Esperar la interpretación nada más acabar la captura

**Síntoma.** Los indicadores están pero la interpretación no; un timeout HTTP corto corta un `/analyze` bloqueante (`504`), o el SDK acaba con `E_INTERPRETATION_TIMEOUT`.

**Causa.** La interpretación se genera cuando la posición se completa y tarda de decenas de segundos hasta unos dos minutos (`constellation.complete` se midió unos 82 s después del primer lote).

**Qué hacer.** Enseña antes los indicadores y la interpretación cuando llegue. Espera `constellation.complete` y llama después a `POST /analyze`; si lo llamas bloqueante, dale un timeout largo. No abortes la captura por `E_INTERPRETATION_TIMEOUT`: pide la interpretación otra vez más tarde.

Afecta a: todas las versiones publicadas del SDK · API.

Más: [Timeouts](/docs/es/guides/timeouts/) · [Timeouts](/docs/es/guides/timeouts/) · [Límites declarados y modos de fallo](/docs/es/concepts/limits/)

### Leer un `202` de `/analyze` como «sin interpretación»

**Síntoma.** `POST /analyze` responde `202` con `ANALYSIS_IN_PROGRESS` y sin interpretación, y tu app enseña «sin interpretación»: por HTTP, o porque `client.analyze()` en la página o `admin.analyze` en tu backend devuelven `interpretation: null`; con un SDK anterior a la 0.44.0, la captura además acababa con `E_INTERPRETATION_TIMEOUT`.

**Causa.** Engine aún está analizando esa sesión (el análisis que lanza tras la captura, o un `reAnalyze`) y no arranca otro. Desde `@neurologyca/capture` 0.44.0 y `capture-server` 0.20.0 el SDK lo dice: `client.analyze()` y `admin.analyze` devuelven `inProgress: true` y `retryAfterMs` junto a `interpretation: null`, y al cerrar una captura el SDK espera y vuelve a pedirla (`analysis.in-progress`), y acaba con `E_ANALYSIS_IN_PROGRESS` (recuperable) si se agota la espera. El código que solo lee `interpretation`, un SDK anterior o un cliente de la API HTTP lo siguen confundiendo con «sin interpretación».

**Qué hacer.** Un `202` cuenta como «interpretando», nunca como «sin interpretación». Con el SDK, mira `inProgress` antes de dar por definitivo un `interpretation: null`, espera `retryAfterMs` (unos 30 s si es `null`) y vuelve a pedirla unas pocas veces como mucho; tras `E_ANALYSIS_IN_PROGRESS`, enseña los resultados y lee la interpretación más tarde. Por HTTP, mira `reason === 'ANALYSIS_IN_PROGRESS'` y espera `retryAfterSeconds` (también la cabecera `Retry-After`). Si sigue en curso, enséñala como «interpretando» y pídela más tarde, o espera `constellation.complete` en el stream. El patrón, para la página y para tu backend, es `askInterpretation` en Errores (El 202 de la interpretación).

Afecta a: todas las versiones publicadas del SDK (antes de la 0.44.0 el SDK no lo distingue; desde la 0.44.0, el código que ignora inProgress) · API.

Más: [HCIs y resultados](/docs/es/concepts/results/) · [Errores, avisos y reintentos](/docs/es/sdk/errors/) · [Límites declarados y modos de fallo](/docs/es/concepts/limits/)

### Enseñar como resultado una interpretación fallida

**Síntoma.** La persona ve una interpretación genérica o vacía, aunque `/analyze` respondió `200`.

**Causa.** Una interpretación con `metadata.status: "failed"` es un marcador (el SDK da `E_ANALYSIS_FAILED`); con `"degraded"` se hizo con datos parciales (el SDK avisa `analysis.degraded`). El porqué está en los `warnings` de la raíz de la respuesta.

**Qué hacer.** No enseñes nunca una interpretación `failed`; enseña los indicadores, que siguen valiendo. Una `degraded`, enséñala con un aviso.

Afecta a: todas las versiones publicadas del SDK · API.

Más: [HCIs y resultados](/docs/es/concepts/results/) · [Errores, avisos y reintentos](/docs/es/sdk/errors/)

### Dar por ausente Effective Active Attention en la primera lectura tras el Final

**Síntoma.** `session.effective_active_attention` vuelve `null` en la lectura de `/results` justo tras el Final, aunque la sesión se midió y tu contexto lo incluye.

**Causa.** Engine puede estar calculando todavía el valor de la sesión cuando los resultados por frame y por step ya están (visto en el Engine de pruebas, por la vía del SDK). Es **Preview**.

**Qué hacer.** No lo des por ausente en la primera lectura: vuelve a leer `/results` un poco después y enséñalo cuando llegue `v`; `null` definitivo es que no se midió o que no está en tu contexto.

Afecta a: todas las versiones publicadas del SDK · API.

Más: [HCIs y resultados](/docs/es/concepts/results/) · [Mostrar y aprovechar los resultados](/docs/es/guides/show-results/)

### Leer la interpretación por título o por `insight`

**Síntoma.** Tu página enseña un resumen vacío o confunde dos secciones de la interpretación.

**Causa.** `structured_data.insight` puede llegar `null`, y los títulos de las secciones se escriben para la audiencia y pueden repetirse. `structured_data.headline` también puede faltar (por diseño en las interpretaciones de selección).

**Qué hacer.** Si `insight` es `null`, enseña `structured_data.headline`. Si `headline` también falta, enseña la primera entrada de `sections[]`, y mira `metadata.status`. Identifica las secciones por `sections[].key`, nunca por `title`.

Afecta a: todas las versiones publicadas del SDK · API.

Más: [HCIs y resultados](/docs/es/concepts/results/)

### Un subcontexto mal escrito cae al de por defecto sin error

**Síntoma.** La interpretación no sigue el subcontexto que fijaste y nada dio error.

**Causa.** El subcontexto es opcional: sin él, Engine aplica el de la mecánica (`constellationSubcontextId`) o, si la mecánica no declara ninguno, el de por defecto del contexto; un `subcontextId` que no conoce cae a ese de por defecto en silencio.

**Qué hacer.** Mejor omitirlo que adivinarlo. Si lo fijas, tómalo de tu kit y compruébalo contra `taxonomy.subcontexts` de `GET /catalog/contexts`.

Afecta a: todas las versiones publicadas del SDK · API.

Más: [Protocolos y su jerarquía](/docs/es/concepts/protocols/) · [Guía de la API HTTP](/docs/es/api/)

### Una etiqueta de audiencia que Engine no conoce

**Síntoma.** La interpretación no encaja con la audiencia que pediste y no hubo error.

**Causa.** Engine no valida la etiqueta de audiencia: una desconocida se acepta sin error.

**Qué hacer.** Usa solo las audiencias que tu kit lista para el contexto del protocolo (`KIT.md`, Audiencias); nunca compongas la etiqueta a partir de texto libre.

Afecta a: todas las versiones publicadas del SDK · API.

Más: [HCIs y resultados](/docs/es/concepts/results/) · [Guía de la API HTTP](/docs/es/api/)

### Una sola audiencia para todas las personas y todos los contextos

**Síntoma.** Tu app fija la misma audiencia en todas las personas (por ejemplo, desde un ajuste de entorno), y las lecturas de algunos contextos salen para un lector para el que no se escribieron, o `audience_applied` no es la que fijaste.

**Causa.** Una audiencia es de un contexto: cada contexto tiene su lista (algunos ninguna, y una puede ser la de por defecto), y una etiqueta solo significa algo en su contexto. Vive en la persona (`POST /users`, `PATCH /users/{externalId}`) o en cada `POST /analyze`, y la de la persona vale para todos los contextos en que se la mide. Engine no la valida: una que el contexto no tiene cae en la lectura por defecto sin error.

**Qué hacer.** Elige la audiencia por protocolo, solo entre las que `KIT.md` lista para él (Audiencias); déjala vacía para la lectura por defecto del contexto. Si a una persona se la mide en contextos con audiencias distintas, fija la suya antes de cada captura (`PATCH /users/{externalId}`, `admin.updateUser`), como hace el playground, o vuelve a leer desde tu backend con `admin.analyze(pair, { audience })`; y compara `audience_applied` con la que querías.

Afecta a: todas las versiones publicadas del SDK · API.

Más: [HCIs y resultados](/docs/es/concepts/results/) · [Tu kit](/docs/es/access/kit/)

### Comparar interpretaciones que salieron de la caché, o forzarlas en bucle

**Síntoma.** Volver a pedir `POST /analyze` devuelve exactamente la misma interpretación, aunque algo haya cambiado; o la factura crece con cada lectura.

**Causa.** Engine guarda una interpretación por sesión y audiencia y la devuelve con `from_cache: true`. `reAnalyze: true` se salta eso y genera una nueva, que se paga cada vez.

**Qué hacer.** Mira `from_cache` antes de comparar dos lecturas. Para una nueva, envía `reAnalyze: true` (con ese nombre exacto) desde tu backend por una decisión deliberada, nunca en bucle ni en cada lectura; la siguiente petición normal devuelve la nueva.

Afecta a: todas las versiones publicadas del SDK · API.

Más: [HCIs y resultados](/docs/es/concepts/results/) · [Proxy a mano](/docs/es/api/proxy/)

### Reconectar el stream con el mismo token tras un cambio de credencial

**Síntoma.** El stream de eventos se cierra con `stream.end` y un `reason` que empieza por `credential_`, y reconectar con el mismo token falla.

**Causa.** La credencial que acuñó el token se rotó, se revocó, se borró, caducó o cambió de alcance: ese token ya no se acepta.

**Qué hacer.** Acuña un token nuevo con una key válida (la nueva tras una rotación; la misma tras un cambio de alcance) y reconecta. Con una key revocada, borrada o caducada, consigue antes una válida.

Afecta a: todas las versiones publicadas del SDK · API.

Más: [Autenticación](/docs/es/start/authentication/)

### Toda interpretación se rechaza para tu organización

**Síntoma.** Las capturas y los indicadores van bien, pero toda interpretación responde `422`. Hoy el cuerpo solo trae `code` y un `message` genérico, y el SDK lo da como `E_TAXONOMY_REJECTED` (`E_TENANT_UNKNOWN` no se emite con el SDK 0.40.0).

**Causa.** Tu organización aún no está activa en el servicio de interpretación. No es tu captura ni tu taxonomía, pero la respuesta ya no distingue los dos casos.

**Qué hacer.** No vuelvas a capturar: los indicadores están guardados. Compara los ids de la taxonomía con los del protocolo; si coinciden y falla toda interpretación, avisa a Neurologyca y, cuando esté resuelto, pide de nuevo la interpretación sobre el mismo par.

Afecta a: todas las versiones publicadas del SDK · API.

Más: [Errores, avisos y reintentos](/docs/es/sdk/errors/) · [HCIs y resultados](/docs/es/concepts/results/)

### Transcribir en un idioma que la persona no habla

**Síntoma.** En el dispositivo, los steps de voz llegan a Engine sin texto o con muy poco (solo el aviso `stt.silent`, si no queda ninguna locución), o con un texto fluido traducido al idioma declarado y sin ningún aviso. En diferido, el transcrito llega con la etiqueta del idioma que pediste (`speech.language`) sea cual sea el idioma hablado, y su texto no es fiable.

**Causa.** El idioma se declara, nunca se detecta: en el dispositivo kodec, y en diferido el servicio de procesado, obligan al modelo a usarlo. Si se habla otro, el modelo o bien traduce al declarado, con fluidez y buena confianza, así que nada lo filtra, o bien se repite o puntúa bajo, y en el dispositivo kodec descarta a propósito esas locuciones (`low-confidence`, `repetition-loop`). Depende del par de idiomas: en una prueba, inglés declarado sobre voz en español volvió traducido; español declarado sobre voz en inglés se descartó casi todo. Fijar el idioma equivocado es peor que no fijarlo. Por defecto (`<html lang>`, y si no, el del navegador) es el idioma de la página, que no siempre es el de la persona. El playground lo hace explícito: su mando «Idioma hablado» es el idioma que se habla en la sesión, y el Vídeo de muestra queda fijo en inglés porque es lo que dice.

**Qué hacer.** Declara, en cada captura, el idioma en el que hablará la persona: `transcribe: { language }` en el dispositivo, el `language` del trabajo en diferido. Formas de acertar: guárdalo con la persona o la entrevista en tu backend (el idioma en el que responde el candidato, por ejemplo) y pásalo a cada captura; si no lo sabes, pregúntalo antes de capturar, en la pantalla del consentimiento; un idioma por captura (quien cambia de idioma a mitad se transcribe en el declarado: divídelo en capturas). Para detectarlo después, lee `SessionReport.transcription` (`onReport`): `vad.utterances` por encima de 0 con pocos o ningún `emitted` y `discardedLowConfidence` o `discardedRepetitionLoop` altos apuntan al idioma equivocado (sin ninguno emitido, el SDK avisa `stt.silent`); ofrece repetir la captura en el correcto. Una traducción pasa todos los contadores: solo declarar el idioma correcto la evita. No pases a `language: null` para esquivarlo: en una prueba, la autodetección también tradujo al inglés las respuestas más largas en español. El idioma de la interpretación va aparte: `narrative.language` en la persona. En el playground, elige «Idioma» según lo que se hable (con la cámara empieza en el idioma de la página).

Afecta a: todas las versiones publicadas del SDK.

Más: [CSP y transcripción](/docs/es/guides/csp-transcription/) · [Diferido (en servidor)](/docs/es/sdk/deferred/)

### Un step con varias preguntas y ninguna declarada

**Síntoma.** La interpretación no menciona la pregunta que respondió la persona: `metadata.missing_inputs` incluye `question_text` y el `status` no es `degraded`, así que nada parece fallar. Con el SDK, `onWarning` recibe `step.media-undeclared`. En `/results`, el mismo `questionText` en varios steps de `speech` (solo en el Engine del entorno de pruebas) es el mismo síntoma: la pregunta no se eligió por step.

**Causa.** El step ofrece varias medias (preguntas alternativas) y la captura no dijo cuál vio la persona: sin `mediaPid` en `start()` o `run()` (SDK), sin `mediaId` en los lotes del step (API HTTP). `text` de `describeStep(step)` es solo el primer texto que casa con el idioma, así que tomarlo es adivinar. Por HTTP, Engine no comprueba que el `mediaId` sea del step, así que una media de otro step pasa sin error. El aviso del SDK no salta en steps con fases, porque ahí las medias de texto son las pautas de cada fase, no preguntas alternativas (no hay nada que elegir). Un `mediaPid` que no es del step lanza `E_MEDIA_UNKNOWN`.

**Qué hacer.** En cada step con más de una pregunta, enseña una y declárala: elígela de `describeStep(step).texts` (cada entrada trae su `mediaPid` y su `body`) o de `plan.steps[].media`, y pásala como `mediaPid` (SDK) o como `mediaId` en todos los lotes del step (HTTP). No repitas la misma pregunta en varios steps de un protocolo. El kit y los starters guardan esta elección en `neuro.config.json` (`media`, por step), con un valor por defecto; el mando «Preguntas» del playground deja elegir antes de medir.

Afecta a: todas las versiones publicadas del SDK · API.

Más: [Steps y marcado](/docs/es/sdk/steps/) · [Errores, avisos y reintentos](/docs/es/sdk/errors/)

### Un step de pregunta enseñado como step de respuesta

**Síntoma.** Tu página marca como «responde ahora» el step que hace la pregunta (o abre ahí el tiempo de respuesta), así que la persona responde antes de leer u oír la pregunta; o el step de respuesta enseña su propia línea y la pregunta desaparece de la pantalla.

**Causa.** El papel del step se dedujo del nombre de su tipo, de `responseClock` o de que no tuviera reloj. Lo dice el catálogo: un step de respuesta es `category: 'answer'` o `expectsSpeech: 'yes'`. Con el SDK, `describeStep` (`StepFacts`) da `expectsSpeech` pero hoy no `category` ni `delivery.media_from`: están en el step del plan (`PlanStep`).

**Qué hacer.** Lee `category`, `expectsSpeech` y `delivery.media_from` de los steps del plan (`session.plan.steps` con el SDK). Cada step enseña su media; sin ella, la pregunta del step anterior (`media_from: 'previous_step'`) o el texto del siguiente (`'next_step'`, un step de lectura en silencio: no declara `mediaPid`). Un step de respuesta mantiene en pantalla la pregunta anterior, con su propia media como la línea de debajo. Nunca enseñes `delivery.instructions` ni `delivery.prompt`.

Afecta a: todas las versiones publicadas del SDK · API.

Más: [Steps y marcado](/docs/es/sdk/steps/)

### La pregunta de `speech` vuelve en otro idioma, o no vuelve

**Síntoma.** En `/results`, `speech` da el `questionText` de un step en un idioma distinto del que se mostró o se habló, o no da `questionText`, aunque `transcript` sí esté.

**Causa.** Engine escribe `questionText` en el idioma de la narrativa de la persona (`narrative.language`), no en el que se mostró ni en el que se habló. Una persona creada sin ese idioma no recibe `questionText`.

**Qué hacer.** Fija `narrative: { language }` al crear a la persona (`createUser`/`updateUser`), el idioma en que quieres leer. Para enseñar la pregunta tal como salió en pantalla, guarda el `mediaPid` que elegiste y lee su `body`. Relacionadas: «La interpretación vuelve en el idioma equivocado», «El transcrito vuelve en inglés» y «Transcribir en un idioma que la persona no habla».

Afecta a: API · todas las versiones publicadas del SDK.

Más: [HCIs y resultados](/docs/es/concepts/results/) · [Tu backend](/docs/es/sdk/backend/)

### Unir los `transcript` de cada step para tener el texto entero

**Síntoma.** Unir los `transcript` de `speech` da menos de lo que dijo la persona: faltan palabras del principio o del final, o un step no tiene ninguno.

**Causa.** `transcript` es lo dicho que tu app situó en ese step (`sttByStep`). El SDK reparte la voz por los límites de los steps; lo dicho fuera de un step (antes del primero, entre dos, después del último) no tiene step y no aparece.

**Qué hacer.** Lee `speech` por step, para lo dicho en cada uno. Para el texto entero, guárdalo en el dispositivo según llega, con `onTranscript` en la captura, o guarda el `speech.text` que tu backend mandó en el `Final`.

Afecta a: API · todas las versiones publicadas del SDK.

Más: [HCIs y resultados](/docs/es/concepts/results/) · [Guía de la API HTTP](/docs/es/api/)

### Buscar en `/results` los indicadores que necesitan sesiones previas

**Síntoma.** Mental Fatigue Load, Facial Muscle Tension, Disengagement o Emotional Mental Control nunca aparecen en `/results`, ni siquiera tras varias sesiones de la misma persona.

**Causa.** Estos cuatro necesitan el historial de la persona: 5 sesiones previas completadas en el mismo contexto (el baseline no cuenta), así que tienen valor desde la 6.ª; Facial Muscle Tension, desde la 1.ª si el contexto tiene datos de calibración de Neurologyca. Aun así, Engine solo los usa dentro de la interpretación (`/analyze`): ninguna ruta devuelve su valor, y aún no están en la producción de Engine.

**Qué hacer.** No los esperes en `/results` ni construyas sobre sus valores. Mantén la misma persona (`externalId`) y el mismo contexto entre sesiones para que la interpretación pueda usarlos, y lee los indicadores por frame que sí llegan.

Afecta a: todas las versiones publicadas del SDK · API.

Más: [HCIs y resultados](/docs/es/concepts/results/)

### Attention pintada en un eje de 0 a 100

**Síntoma.** La barra o la línea de Attention queda plana abajo en un gráfico compartido con los demás indicadores, o una media como `0.83` se enseña como «0,83» o «1 %».

**Causa.** Attention no está en la escala de 0 a 100: vale 0 o 1 por frame, y su media en `/results` es la fracción de frames con atención, de 0 a 1. Los demás indicadores van de 0 a 100, salvo Valence y Motivation, de −100 a 100.

**Qué hacer.** Pinta Attention por frame como una banda de sí/no, no en el eje de 0 a 100, y enseña su media como porcentaje de frames (× 100: «83 % de los frames con atención»). Effective Active Attention (`session.effective_active_attention.v`, Preview) ya es un porcentaje de 0 a 100: no lo multipliques.

Afecta a: todas las versiones publicadas del SDK · API.

Más: [HCIs y resultados](/docs/es/concepts/results/) · [Mostrar y aprovechar los resultados](/docs/es/guides/show-results/)

### Un indicador que llega en el ejemplo y no en tu captura

**Síntoma.** Un indicador que ves en el ejemplo grabado del playground, en esta documentación o en otro protocolo falta en tus `rawResults` y `aggResults`, `session` llega en `null` o un Relevante de la interpretación no está en tu `/results`; la captura acaba con normalidad.

**Causa.** Qué indicadores recibes depende del contexto y del acuerdo de tu organización. Todo contexto interpretado incluye los que su interpretación necesita; el resto del catálogo público llega bajo acuerdo, y la lista puede cambiar con él. Los ejemplos grabados llevan todo el catálogo público. No es el caso de los cuatro que necesitan sesiones previas, que no llegan en `/results` para nadie.

**Qué hacer.** Mira los indicadores de cada protocolo en Tu integración › Protocolos («Indicadores que recibes en este contexto»); cuando tu contexto no los incluye todos, Resultados del playground dice cuántos (tras una sesión). Trata como opcional todo indicador: una clave que falta no se ha recibido, nunca es un cero. Para recibir más, pídeselo a Neurologyca.

Afecta a: todas las versiones publicadas del SDK · API.

Más: [HCIs y resultados](/docs/es/concepts/results/) · [Tu cuenta de DevLab](/docs/es/access/account/)

### La interpretación vuelve en el idioma equivocado

**Síntoma.** El transcrito está en el idioma correcto (fijaste `transcribe: { language }`), pero la interpretación que devuelve Engine sale en inglés para una captura en español.

**Causa.** El idioma de la interpretación se fija en la persona, con `narrative.language` (default `en`), no con `transcribe.language` (eso es el transcrito) ni en `/analyze` (que no lleva idioma). El backend del SDK envía `narrativeLanguage: 'en'` si no fijas `narrative.language`.

**Qué hacer.** Crea o actualiza la persona con `narrative: { language }` (`createUser`/`updateUser`) y vuelve a pedir la interpretación. `/analyze/stream` recalcula siempre; `/analyze` necesita `reAnalyze: true` desde tu backend.

Afecta a: todas las versiones publicadas del SDK.

Más: [Tu backend](/docs/es/sdk/backend/) · [HCIs y resultados](/docs/es/concepts/results/)
