Ir al contenido
DevLab

Errores, avisos y reintentos

Cada error y aviso del SDK, por capa y por modo, lo que el SDK reintenta solo y qué mandar a soporte.

En esta página
  1. La regla que costó un incidente
  2. Tres familias
  3. En el dispositivo
  4. Errores de uso
  5. Avisos que conviene mostrar
  6. Diferido, en el navegador
  7. Diferido, en tu backend
  8. Los errores HTTP de Engine
  9. El 202 de la interpretación
  10. Lo que el SDK reintenta solo
  11. Soporte

Un recoverable distinto de true durante los steps da la captura por perdida: llama a abort(); después de stop(), no: códigos como E_RESULTS_TIMEOUT o E_INTERPRETATION_TIMEOUT también llegan con recoverable: false, pero Engine ya tiene la captura, y abortar ahí la destruiría.

Los fallos del pipeline llegan por onError ({ code, message, recoverable, stepOrder? }). Los errores de uso se lanzan a quien llama (clases que extienden ProtocolUsageError, con un code). Los avisos llegan por onWarning ({ code, message, stepOrder? }) y nunca paran la captura.

Nota: los mensajes del SDK están en inglés; los códigos son los mismos.

Los códigos del pipeline de onError (la unión publicada ProtocolErrorCode):

Código Qué significa Qué hacer
E_HTTP GET /results falló repetidamente en el transporte Casi siempre el proxy o la red. Guarda el par y lee los resultados más tarde
E_RESULTS_TIMEOUT Ningún intento completado dentro de outcomeDeadlineMs (240 s por defecto). No es una pérdida: Engine aceptó la captura y sigue procesándola No captures de nuevo. Recupérala con client.retrieveResults(userProtocolId, protocolMechanicId) (o admin.getResults desde tu backend): guarda esos dos ids fuera de la pestaña. En capturas largas, sube outcomeDeadlineMs
E_RESULTS_EMPTY El intento se completó y /results siguió vacío Un fallo real: guarda el par y repórtalo
E_INTERPRETATION_TIMEOUT Había indicadores pero no interpretación: el aviso de Engine no llegó por el flujo de eventos (o, con interpretation: 'stream', el stream se calló) y /analyze no la dio. Desde la 0.44.0 un 202 (ANALYSIS_IN_PROGRESS) ya no acaba aquí: mira E_ANALYSIS_IN_PROGRESS No abortes. Muestra los indicadores y pide la interpretación más tarde (client.analyze() o admin.analyze()), o espera constellation.complete
E_ANALYSIS_IN_PROGRESS Desde la 0.44.0, con recoverable: true y estado timeout. Al cerrar, /analyze respondió 202 ANALYSIS_IN_PROGRESS (ya había un análisis de la sesión en curso): el SDK esperó lo que Engine pidió (30 s si no lo dice, nunca menos de 1 s), sin dejar de escuchar el aviso de Engine, y volvió a pedirla, dentro de analyzeTimeoutMs contado desde el primer 202; la espera se agotó con Engine aún escribiéndola. Desde la 0.45.0 también acaba aquí si un /analyze repetido no recibe ninguna respuesta, y el cierre acaba como mucho unos 10 s después de ese límite No se pierde nada: los resultados ya llegaron. Enséñalos, di que la interpretación aún se está escribiendo y léela más tarde con client.analyze() (o admin.analyze() desde tu backend), como abajo; o sube analyzeTimeoutMs
E_PROCESSING Engine informó de un error de procesado (el mensaje dice la categoría) La sesión queda invalidada. Aun así se emiten resultados parciales si algún intento llegó a completarse
E_FRAMES_DISCARDED kpi_source=frames_discarded: el servicio de interpretación descartó todos los frames y analizó desde agregados. Vuelve como un 200 Casi siempre es el número de landmarks. Revisa la versión de kodec. Se esperan 478 (468 de la cara + 10 del iris). Con 468, medido el 9-ago-2026, Engine aceptó todos los lotes y la sesión no se cerró nunca; un frame sin cara (landmarks: []) no está medido
E_UPLOAD_FAILED La subida de un lote parcial falló y el SDK dejó de enviar. Un 4xx (por ejemplo un 413 de tu proxy) es terminal al primer intento; un 5xx o un error de red se reintenta antes (3 intentos, 30 s) La sesión queda inválida. Un 413 significa que el tope de cuerpo de tu proxy es demasiado bajo (Tu backend); si no, reintenta cuando el par esté libre
E_STEP_LOST El Final de un step murió sin forma de saber si el servidor lo marcó. El SDK no lo reintenta, a propósito: un paquete tardío sobre una sesión ya completa crea una sesión zombi que bloquea el par La sesión está perdida. Espera a que el barrido libere el par (unos 5 min, marcado abandoned) y reintenta
E_CAPTURE_LOST La pista de vídeo de la cámara terminó con la sesión viva (cámara desconectada o permiso retirado). Solo con { type: 'webcam' }. Invalida la sesión aunque no hubiera un step abierto abort() y captura de nuevo
E_RECORDING_LOST Se perdió la grabación con la sesión viva: la pista de vídeo de la cámara terminó, el grabador falló o el dispositivo no pudo guardar un trozo No se entrega nada. Llama a abort() (libera la reserva) y graba otra vez
E_AXES_MISSING Se rechazó el análisis porque falta un eje del Circumplex. Casi seguro a tus frames les falta featuresMeta; solo pasa con una fuente de frames propia. Hoy no se emite (SDK 0.45.0): ese caso llega como E_TAXONOMY_REJECTED No captures de nuevo: los indicadores están guardados, pide la interpretación otra vez. Comprueba que cada frame lleve featuresMeta
E_NARRATIVE_REJECTED La narrativa de la persona (voice o depth) se rechazó después de la captura; Engine acepta cualquier valor con un 200. Hoy no se emite (SDK 0.45.0): ese caso llega como E_TAXONOMY_REJECTED Corrígela en la persona (voice: second o third; depth: standard o professional) y pide la interpretación otra vez. No captures de nuevo
E_TAXONOMY_REJECTED Un 422 de /analyze. Hoy todo 422 llega aquí, sea cual sea su causa: Engine ya no manda el detalle del servicio de interpretación, y el SDK (también la 0.45.0) los clasifica por ese texto. Así que también cubre los casos de E_AXES_MISSING, E_NARRATIVE_REJECTED y E_TENANT_UNKNOWN, y sus causas tienen arreglos opuestos Comprueba antes de volver a grabar a nadie. Con una fuente de frames propia: que cada frame lleve featuresMeta. La persona: que voice y depth sean válidos. El id: si es erróneo para el protocolo, la taxonomía se congela al capturar, así que captura de nuevo con el correcto. Si todo coincide, se arregla sin recapturar (consulta con Neurologyca) y /analyze sobre el mismo par funciona después
E_TENANT_UNKNOWN El servicio de interpretación no tiene un registro activo de tu organización. La credencial sí se aceptó. Hoy no se emite (SDK 0.45.0): ese caso llega como E_TAXONOMY_REJECTED No captures de nuevo: no es la captura ni la taxonomía. Consulta con Neurologyca; cuando esté arreglado, pide la interpretación otra vez
E_ANALYSIS_FAILED El análisis volvió como fallido: su interpretación es un marcador de posición, con un 200 No la muestres como resultado. El motivo está en los warnings de la raíz del payload. Los indicadores siguen siendo válidos
E_CONFLICT Un 409 de Engine Lee reason y conflict.<campo>

E_CONFLICT llega con reason y conflict (expired, goToPosition, earliestAt, expected, rule, hint, holder, captureId). Los once motivos (CONFLICT_REASONS):

  • SESSION_ABANDONED: la captura se abandonó. Empieza otra vez desde el step 1.
  • POSITION_ALREADY_COMPLETED: la posición ya tiene una sesión completada. No captures de nuevo.
  • MECHANIC_EXPIRED: su ventana se cerró para siempre. Sigue con conflict.goToPosition.
  • MECHANIC_NOT_YET_AVAILABLE: la posición aún no está abierta. Vuelve a intentarlo en conflict.earliestAt.
  • MUST_START_AT_FIRST_POSITION: un protocolo con calendario empieza por su primera posición. Empieza por conflict.goToPosition.
  • PROTOCOL_DEPRECATED: el protocolo se retiró. Usa el que lo sustituye.
  • POSITION_RESERVED: otro intento tiene la posición (conflict.holder). Pregunta a la persona antes de descartarlo.
  • CAPTURE_DISCARDED: esa grabación se descartó. No reintentes.
  • CAPTURE_OUT_OF_ORDER: la grabación es anterior a la última sesión analizada de la persona. No reintentes.
  • PROTOCOL_NOT_ANALYSED (desde 0.28.0): /analyze en un protocolo que no se interpreta, como Measurement. Los indicadores ya llegaron; lo que falta es una interpretación. Desde 0.29.0 el SDK no pide análisis cuando Engine dice interpreted: false, y si este 409 llega de todos modos (un Engine que no devuelve interpreted), la sesión acaba complete con sus indicadores: es el final normal. client.analyze() en un protocolo así lo sigue lanzando.
  • CAPTURE_CANCELLED (desde 0.29.0, solo en grabación): el aviso de fin de una grabación cuya reserva ya se había cancelado (o cerrado como CAPTURE_OUT_OF_ORDER). El SDK no lo reintenta, lo dice una vez con recording.end-notice-failed y entrega la grabación igualmente: procesarla vuelve a reservar la posición.

El SDK también emite tres avisos sobre el propio conflicto (CONFLICT_WARNINGS): conflict.unknown-reason (un reason que esta versión no conoce: reason es un string, así que ramifica con un caso por defecto), conflict.ambiguous-goto y conflict.earliestAt-assumed-utc.

Se lanzan a tu código, antes o entre los steps, nunca por onError:

Código Cuándo
E_STEP_SEQUENCE Un step se inicia o se cierra fuera del orden del plan
E_STEP_DURATION Un step terminó fuera de su ventana, con stepDurations: 'enforce'
E_PLAN_INCOMPLETE stop() con steps del plan sin hacer
E_SESSION_DIRTY El par ya tiene un intento sin terminar
E_CADENCE_BLOCKED La posición aún no está disponible (availableAt dice cuándo)
E_SESSION_INVALID La sesión quedó invalidada por un error anterior, o la fuente terminó: llama a abort()
E_MEDIA_UNKNOWN Un mediaPid que no es del step
E_CAPTURE CaptureStartError: la captura no pudo arrancar. Desde la 0.42.0 lleva siempre stage y reason: 'face-model' ('timeout': se agotó el tope del modelo de la cara, startup.timeouts.vision.totalMs, 120 s, y subStage dice dónde; 'error': falló la carga), 'first-frame' ('timeout': 15 s sin frame; messageKey first-frame.timeout con la webcam y, desde la 0.42.1, first-frame.timeout-media con tu propio stream o <video> y en una reproducción) o 'source' ('paused' o 'metadata': el <video>; 'error': la fuente no se puede usar), y userMessage. Desde la 0.43.0 (kodec 5.0.0-rc.14), si la fuente ya había terminado al empezar la captura (una pista de stream parada, un dispositivo que se fue, un <video> que acabó), falla en el acto, antes de cargar ningún modelo, con stage: 'source' y reason: 'error', sin E_CAPTURE_LOST ni codec.error: rebobina tu <video> antes de captureProtocol. Una webcam que deja de mandar vídeo mientras arranca la captura falla igual. Y 'first-frame' con 'error' y la clave first-frame.face-reload-failed: el análisis facial se paró al empezar la captura y volver a cargarlo falló. Tras subStage: 'vision-runtime' ofrece recargar, no reintentar. Un getUserMedia denegado llega como el DOMException del navegador, no con este código
E_TAXONOMY_INVALID Un situationId sin hciId; se comprueba antes de abrir la cámara
E_CADENCE_UNKNOWN Como E_CADENCE_BLOCKED, cuando el SDK no puede saber cuándo se abre la posición
E_FLOW_UNSUPPORTED El flowMode de la mecánica no está soportado
E_EMPTY_STEP Un step se cerró sin un solo frame
E_BASELINE_REQUEST Lo lanza client.captureBaseline(): un durationMs o userId no válido, una segunda captura del mismo usuario en curso, o el servidor rechazando la petición
E_BASELINE_INCOMPLETE captureBaseline() fue bien pero faltan paquetes (missingOrders): no hay reintento posible, repite la captura entera
E_UNKNOWN_OPTION Una opción que el SDK no conoce; lanza antes de tocar la cámara. Desde la 0.42.0 createProtocolClient también lo lanza con una clave desconocida (también dentro de startup), como ya hacía createRecordingClient; antes la ignoraba. El mensaje dice dónde va una opción de cada captura (signal, captureId). También sale de prepare({ models: { speech: true } }) en un cliente sin la transcripción del propio SDK, y de cacheStatus() en un cliente en modo grabación
E_CAPTURE_ABORTED CaptureAbortedError (desde la 0.42.0): cancelaste el arranque con el signal de captureProtocol o captureBaseline. Antes se sueltan la cámara, el micrófono y el par; stage dice dónde estaba y userMessage lleva el mensaje capture.aborted. No es un fallo de la cámara
E_PREPARE PrepareError (desde la 0.42.0), de client.prepare(): con throwOnFailure: true, una preparación que acabó 'failed' o 'aborted' (reason, y el PrepareResult entero en result); y siempre, con reason: 'capture-in-progress' y result: null, mientras corre una captura o un baseline de este cliente. Prepara antes, o cuando acabe

Los códigos de onWarning son strings, no una unión publicada: ramifica con un caso por defecto. Los que conviene mostrar o registrar:

  • source.ended: tu archivo o stream terminó; el step abierto se cierra.

  • step.duration-below-min, step.duration-above-max y step.media-undeclared: mira Steps y marcado.

  • capture.throttled es relativo a la propia sesión: salta cuando los fps caen a una cuarta parte de los propios de esa sesión durante tres ventanas seguidas, con un step abierto (una vez por step), normalmente una pestaña oculta. Un dispositivo lento desde la primera ventana nunca lo dispara, así que no es la señal de lo rápido que es el dispositivo (léelo como en Probar en tu móvil).

  • quality.warning: Engine dice que la calidad de lo que le llega no es suficiente.

  • stream.unavailable: el flujo de eventos no conectó; la captura sigue.

  • hci.coverage, analysis.degraded y kpi.aggregate_only: el análisis es parcial o le faltan indicadores.

  • target.inferred y contract.version: el contexto no se fijó como se declaró, o Engine habla otra versión del contrato.

  • protocol.not-interpreted (desde 0.29.0): Engine dice que el protocolo no se interpreta (interpreted: false, Measurement). El SDK no envía taxonomía ni pide análisis, aunque pasaras triggerAnalysis: true; interpretation será null, como se espera. Una vez por captura, en vivo y en grabación.

  • analysis.out-of-token-scope (desde 0.29.0): con un token de captura, que no puede llamar a /analyze*. En vivo, desde 0.38.0, la interpretación llega igualmente por el flujo de eventos, y este aviso solo sale si el aviso de Engine no llega a tiempo y el /analyze de respaldo responde 403; con interpretation: 'stream' no se produce interpretación, así que con un token de captura usa el valor por defecto. En el replay del servicio de procesado (Servicio de procesado), Engine hace la interpretación que pidió el Final de cierre. En los dos casos la sesión acaba complete con sus resultados.

  • interpretation.sse-timeout (desde 0.38.0): el aviso de Engine de que la interpretación está lista no llegó a tiempo (analyzeTimeoutMs, o 120 s si el flujo nunca conectó), y la guardada se leyó con POST /analyze. Dice la causa: un flujo que nunca conectó, uno que se cortó durante la espera (SessionReport.streamDropsDuringWait; comprueba que tu proxy reenvía /stream/{userProtocolId}) o un Engine más lento que analyzeTimeoutMs.

  • analysis.in-progress (desde 0.44.0): al cerrar una captura, POST /analyze respondió 202 ANALYSIS_IN_PROGRESS; uno por cada respuesta así. El SDK espera y vuelve a pedirla solo: di «interpretando», no «sin interpretación». Desde la 0.45.0, interpretation.sse-timeout y analysis.regenerated tras un 202 cuentan esa espera en el tiempo que dicen

  • analysis.regenerated (desde 0.38.0): POST /analyze respondió from_cache: false, así que generó una interpretación nueva en vez de servir la guardada; la sesión pudo cobrarse dos veces.

  • analyze.progress: obsoleto, y desde 0.38.0 solo con interpretation: 'stream' y sin onProgress en el cliente. Pasa onProgress({ phase, route }) para recibir ahí las fases.

  • transport.rate-limited (desde 0.37.0): con un token de captura, Engine limitó las peticiones de esta captura (429 CAPTURE_TOKEN_RATE_LIMIT) y el SDK espera el Retry-After antes de volver a enviar la misma petición; dice la ruta y la espera. No se pierde nada: la captura sigue, más lenta. Como mucho 2 minutos cada vez y 5 veces seguidas por petición; pasado eso, la petición falla como antes.

  • score-index.malformed (desde 0.39.0): readScoreIndex() encontró la clave del índice en los datos estructurados de la interpretación, pero con una forma que no reconoce, y devolvió null. Solo sale si le pasas onWarning a readScoreIndex(); en capture-server es un texto que empieza por score-index.malformed:. Ver Resultados.

  • Transcripción: stt (con un blocker, el dispositivo no puede transcribir; con una fuente { type: 'video' } o { type: 'stream' } sin pista de audio, desde la 0.43.0 el mensaje lo dice (la fuente de captura no tiene pista de audio, así que no hay nada que transcribir y esta captura sigue sin transcripción): usa una fuente con sonido o pon transcribe: false; en otro caso, no pudo arrancar, por ejemplo una CSP sin blob: en script-src, y entonces la transcription del informe es null), stt.cut (cortada a mitad de sesión), stt.autodetect (el idioma se detectó, no se fijó: el texto puede volver traducido al inglés), stt.discarded (voz de un step que descartó un filtro y no llegó al transcrito: baja confianza, un bucle de repetición, la puerta Silero o el corte anti-atasco), stt.speechDiscarded (un tramo de ruido continuo descartado antes del modelo), stt.silent (el micrófono funcionó y no se transcribió nada: mira los transcription.discarded* del informe) y stt.mainThread (la voz corre en el hilo principal: cada frase para el vídeo, espera menos frames). Desde la 0.43.0, con allowWasmWorker (sin WebGPU), un Worker de transcripción que no arranca ya no cae al hilo principal: no hay transcripción (codec.error con wasm-needs-worker, y SessionReport.transcriptionLoad.reason es 'needs-worker') y la captura sigue sin voz. El transcription.lostOnClose del informe cuenta las frases que aún se transcribían o esperaban al parar la captura; desde la 0.43.0 incluye una cortada por un abort() o un stop() a mitad de un step, donde antes podía leer 0. Ver CSP y transcripción.

  • Transcripción por step, antes de abrir la cámara (desde 0.38.0): transcription.off-on-voice-step (transcribe está apagado y el plan tiene steps en los que se espera que la persona hable, expectsSpeech: 'yes'; dice sus tipos), transcribeSteps.excludes-voice-step (transcribeSteps deja fuera uno de esos steps) y transcribeSteps.noMatch (ningún tipo de transcribeSteps existe en el plan: no se transcribe ningún step). transcribeSteps.unknownType ahora solo significa que algunos de los tipos no existen; los steps que coinciden se siguen transcribiendo.

  • El arranque (desde la 0.42.0): startup.stalled (una descarga de face-model o speech no trae ningún byte nuevo durante stallMs, 20 s por defecto; uno por atasco, con stage, subStage, messageKey y userMessage; no corta nada), stt con reason: 'timeout' (se agotó el tope de la voz: la captura sigue sin voz), prepare.stale (una captura no pudo usar una parte preparada, con part, fields y reason, y la carga ella), prepare.released (se liberó lo que cargó prepare(), con su reason, como 'replaced', 'release', 'abort' o 'pagehide'; desde la 0.43.0, con keepPrepared, también 'unusable' con su part: kodec dejó inservible una parte guardada mientras esperaba la siguiente captura, y solo se suelta esa parte) y, en modo grabación, recording.option-ignored para startup.timeouts.vision y startup.timeouts.speech (una grabación no tiene esas fases). Ver En el dispositivo.

  • La cara (desde la 0.43.0, en una captura y en un baseline): prepare.face-lost (la cara preparada rechazó sus primeros frames o perdió su contexto de GPU, y kodec la vuelve a cargar una vez; el informe mantiene la cara 'adopted', con faceReloaded: true) y face.context-lost (lo mismo con una cara que cargó la propia captura, por un reinicio del driver o al volver de la suspensión: no hay frames mientras recarga). Ninguno es un codec.error. Una segunda pérdida en la misma captura, o una recarga que falla, la paran con capture-failed; en Safari 16.x la pérdida no se puede vigilar y sigue siendo silenciosa.

  • codec.error: kodec lanzó un error, avisado una vez por código y contado en el codecErrors del informe (SessionReport). no-audio-track es informativo (lo tiene toda sesión en vivo sin transcripción); audio-start-failed pierde la transcripción. Desde la 0.43.0 (kodec 5.0.0-rc.14) no cuenta la recarga de la cara de face.context-lost y prepare.face-lost, ni un hueco capture-stalled que caiga dentro de ella; sí cuenta un hueco que empieza antes de la pérdida o acaba después de la recarga, y una cámara perdida (track-ended).

  • baseline.framesLost: solo de captureBaseline(). El servidor confirmó menos frames de un lote de los que llevaba: el resto no está en el baseline y nada los reintenta.

  • audience.not-applied: la audiencia que pediste no se aplicó, y la interpretación llegó con la lectura por defecto. Es la única señal: no hay ninguna ruta para listar las audiencias, así que revisa la etiqueta (Interpretación para una audiencia).

Más en En el dispositivo.

uploadRecording rechaza con UploadRecordingError (code, status, retryable):

Código Cuándo Reintentable Qué hacer
E_UPLOAD_NETWORK Red, 5xx (incluido el 503 E_BUSY, con su Retry-After), 408, 429 o el 409 de una parte, tras los reintentos Sí Vuelve a llamar más tarde: la copia local sigue ahí
E_UPLOAD_NOT_NOTIFIED Tu receptor lo guardó pero su onComplete falló Sí Dile al usuario que está subida; vuelve a llamar más tarde (tu backend puede reintentar onComplete por su cuenta con receiver.notify())
E_UPLOAD_AUTH 401: sin sesión Sí, tras iniciar sesión Inicia la sesión del usuario y vuelve a llamar
E_UPLOAD_REJECTED 403, 400, 413, 415 o demasiadas subidas abiertas No No es de este usuario, o está mal formado
E_UPLOAD_CONFLICT Un 409 que no es una resincronización No Un defecto: repórtalo; no se reintenta
E_UPLOAD_TOO_LARGE Por encima de maxBytes No Graba más corto o con menos bitrate
E_UPLOAD_LOCAL_UNREADABLE La copia local ya no se puede leer No abandonUpload
E_UPLOAD_PROTOCOL Tu receptor contesta algo imposible No Revisa el receptor
E_UPLOAD_ABORTED Tu propio signal Sí Vuelve a llamar cuando quieras reanudar

Y la propia grabación:

Código Cuándo Qué hacer
E_RECORDER_UNSUPPORTED El navegador no puede grabar MP4/H.264 Otro navegador (Firefox no es objetivo: kodec no se ha probado allí, y no graba MP4/H.264)
E_RECORDING_LOST La cámara se para, el grabador falla o el disco está lleno No se guarda nada. abort() para liberar la reserva y graba otra vez
E_STORAGE_FULL No hay espacio para guardar la grabación Libera espacio y graba otra vez
E_CAPTURE_ID_IN_USE Ese captureId ya tiene una grabación en este navegador Sube o abandona la primera

Más en Diferido (en servidor).

Tu receptor contesta con { "error": { "code", "message" } }. Estos son todos los códigos del receptor:

Código Estado Cuándo
E_UNAUTHORIZED 401 No hay sesión autenticada
E_FORBIDDEN 403 El sujeto no puede subir una captura para este par
E_BAD_REQUEST 400 El cuerpo no es JSON, o un id o un offset está mal formado
E_MANIFEST_INVALID 400 El size, el mimeType o el manifiesto no validan
E_NOT_FOUND 404 No existe esa subida (o es de otro sujeto)
E_METHOD_NOT_ALLOWED 405 Un método que la ruta no acepta
E_CAPTURE_ID_CONFLICT 409 Ese captureId pertenece a otra subida
E_MANIFEST_MISMATCH 409 Ese captureId se empezó con otro tamaño, mimeType o manifiesto
E_ALREADY_COMPLETE 409 La subida ya está completa
E_OFFSET_MISMATCH 409 El offset no es donde está la subida (el cuerpo lleva bytes); el cliente resincroniza
E_SIZE_MISMATCH 409 complete con menos bytes que el size declarado
E_UPLOAD_CONFLICT 409 Otro trozo de la misma captura está en vuelo
E_UPLOAD_GONE 410 La subida se procesó y se retiró
E_LENGTH_REQUIRED 411 Una parte sin Content-Length
E_TOO_LARGE 413 El size supera maxBytes
E_BODY_TOO_LARGE 413 El cuerpo supera el límite
E_PART_TOO_LARGE 413 Una parte supera partBytes
E_UNSUPPORTED_MEDIA_TYPE 415 El Content-Type no es el que necesita la ruta
E_TOO_MANY_OPEN 429 El sujeto tiene demasiadas subidas sin terminar
E_STORAGE 500 El almacenamiento no puede contestar con seguridad
E_INTERNAL 500 Un fallo inesperado del receptor
E_BUSY 503 Otro proceso tiene la captura, o su onComplete sigue corriendo; llega con Retry-After
E_NOTIFY_FAILED 503 La subida está guardada pero tu onComplete falló o tardó demasiado; llega con Retry-After: 30

En la ruta del vídeo, E_BAD_SIGNATURE (403) significa una URL de vídeo mala o caducada.

El proxy contesta con la misma forma, más el estado y el cuerpo de Engine tal cual:

Código Estado Cuándo
E_ROUTE_NOT_ALLOWED 404 Una ruta que no está en la lista del proxy
E_METHOD_NOT_ALLOWED 405 Un método que la ruta no acepta
E_FORBIDDEN 403 Tu authorize lo rechazó, o el origen no está permitido
E_BAD_REQUEST 400 Los ids de la ruta están mal formados
E_UNSUPPORTED_MEDIA_TYPE 415 El cuerpo no es application/json
E_BODY_TOO_LARGE 413 El cuerpo supera maxBodyBytes de createEngineProxy (16 MiB por defecto desde capture-server 0.12.0; antes, 8 MiB). El SDK lo ve como E_UPLOAD_FAILED, definitivo al primer intento
E_ENGINE 502 No se pudo llegar a Engine, o no se pudo obtener un token
E_RATE_LIMITED 503 Engine limitó la tasa del token; vuelve a intentarlo más tarde
E_INTERNAL 500 Un fallo inesperado del proxy

El errorCode del servicio de procesado, con si reintentar y si se libera la reserva: Servicio de procesado.

Engine contesta los errores con esta forma:

JSON
{ "status": 401, "body": { "code": 401, "message": "Invalid credentials." } }

code es el estado HTTP. En un 202, 403, 409 o 422 el cuerpo puede llevar además un reason por el que ramificar: están en Límites.

client.analyze(userProtocolId, protocolMechanicId) en la página (@neurologyca/capture 0.44.0 o posterior) y admin.analyze(pair) en tu backend (capture-server 0.20.0 o posterior) no lanzan ante un 202: devuelven interpretation: null con inProgress: true y retryAfterMs (el retryAfterSeconds de Engine en ms o, en la página, su cabecera Retry-After; null si no lo dice), y el cuerpo de Engine en raw (reason: 'ANALYSIS_IN_PROGRESS', raw.retryAfterSeconds). Engine aún está interpretando esa sesión, así que un 202 cuenta como «interpretando», nunca como «sin interpretación»: espera retryAfterMs (unos 30 s si es null), vuelve a pedirla unas pocas veces como mucho y, si sigue en curso, enséñala como «interpretando» y pídela más tarde (o espera constellation.complete en el stream). Solo un null con inProgress: false es definitivo. Un 202 no lanza otro análisis, así que volver a pedirla no se paga otra vez. Al cerrar una captura el SDK ya lo hace solo (analysis.in-progress y, si se agota la espera, E_ANALYSIS_IN_PROGRESS); esta función es para leerla después. Con el proxy en otro origen, la página solo lee Retry-After con capture-server 0.20.1 o posterior (El proxy).

JavaScript
// A 202 from /analyze means "interpreting", not "no interpretation". client.analyze() in the page (@neurologyca/capture
// 0.44.0 or later) and admin.analyze() in your backend (capture-server 0.20.0 or later) say so: interpretation: null,
// inProgress: true and retryAfterMs, the wait Engine asks for (null when it does not say).
/**
* @param {() => Promise<{ interpretation: string | null, inProgress: boolean, retryAfterMs: number | null, raw: unknown }>} ask
* in the page: () => client.analyze(userProtocolId, protocolMechanicId); in your backend: () => admin.analyze(pair)
* @param {{ tries?: number, wait?: (ms: number) => Promise<void> }} [o]
* @returns {Promise<{ interpretation: string | null, interpreting: boolean, raw: unknown }>}
*/
export async function askInterpretation(ask, { tries = 4, wait = (ms) => new Promise((r) => setTimeout(r, ms)) } = {}) {
for (let i = 1; ; i++) {
const { interpretation, inProgress, retryAfterMs, raw } = await ask()
if (!inProgress) return { interpretation, interpreting: false, raw }
if (i >= tries) return { interpretation: null, interpreting: true, raw } // still interpreting: show it so, ask later
await wait(retryAfterMs ?? 30_000) // Engine's wait, else about 30 s
}
}

Lotes: 3 intentos dentro de 30 s. Subidas: 6 intentos, respetando Retry-After; un 504 en complete se reintenta como un 503. El token: una acuñación más tras un 401. Nada más: el resto es cosa tuya.

Escribe al contacto de tu invitación (no está en esta documentación). Manda el X-Correlation-Id que mandó el SDK: hoy Engine no lo devuelve, así que tómalo de tu lado. El SDK lo manda en las llamadas de la interpretación, con el correlationId de tu configuración o, sin él, un id que genera, y session.correlationId lo guarda. Manda también el captureId, la versión del SDK que usas (version en el package.json de @neurologyca/capture), la hora con su zona horaria y el entorno (pruebas o producción). Nunca mandes keys, tokens ni datos de la persona.