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.
La regla que costó un incidente
Sección titulada «La regla que costó un incidente»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.
Tres familias
Sección titulada «Tres familias»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.
En el dispositivo
Sección titulada «En el dispositivo»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 conconflict.goToPosition.MECHANIC_NOT_YET_AVAILABLE: la posición aún no está abierta. Vuelve a intentarlo enconflict.earliestAt.MUST_START_AT_FIRST_POSITION: un protocolo con calendario empieza por su primera posición. Empieza porconflict.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):/analyzeen 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 diceinterpreted: false, y si este 409 llega de todos modos (un Engine que no devuelveinterpreted), la sesión acabacompletecon 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 comoCAPTURE_OUT_OF_ORDER). El SDK no lo reintenta, lo dice una vez conrecording.end-notice-failedy 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.
Errores de uso
Sección titulada «Errores de uso»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 |
Avisos que conviene mostrar
Sección titulada «Avisos que conviene mostrar»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-maxystep.media-undeclared: mira Steps y marcado. -
capture.throttledes 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.degradedykpi.aggregate_only: el análisis es parcial o le faltan indicadores. -
target.inferredycontract.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 pasarastriggerAnalysis: true;interpretationserá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/analyzede respaldo responde403; coninterpretation: '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ó elFinalde cierre. En los dos casos la sesión acabacompletecon 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ó conPOST /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 queanalyzeTimeoutMs. -
analysis.in-progress(desde 0.44.0): al cerrar una captura,POST /analyzerespondió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-timeoutyanalysis.regeneratedtras un202cuentan esa espera en el tiempo que dicen -
analysis.regenerated(desde 0.38.0):POST /analyzerespondió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 coninterpretation: 'stream'y sinonProgressen el cliente. PasaonProgress({ 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 (429CAPTURE_TOKEN_RATE_LIMIT) y el SDK espera elRetry-Afterantes 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 pasasonWarningareadScoreIndex(); encapture-serveres un texto que empieza porscore-index.malformed:. Ver Resultados. -
Transcripción:
stt(con unblocker, 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 pontranscribe: false; en otro caso, no pudo arrancar, por ejemplo una CSP sinblob:enscript-src, y entonces latranscriptiondel informe esnull),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 lostranscription.discarded*del informe) ystt.mainThread(la voz corre en el hilo principal: cada frase para el vídeo, espera menos frames). Desde la 0.43.0, conallowWasmWorker(sin WebGPU), un Worker de transcripción que no arranca ya no cae al hilo principal: no hay transcripción (codec.errorconwasm-needs-worker, ySessionReport.transcriptionLoad.reasones'needs-worker') y la captura sigue sin voz. Eltranscription.lostOnClosedel 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 unabort()o unstop()a mitad de un step, donde antes podía leer0. Ver CSP y transcripción. -
Transcripción por step, antes de abrir la cámara (desde 0.38.0):
transcription.off-on-voice-step(transcribeestá apagado y el plan tiene steps en los que se espera que la persona hable,expectsSpeech: 'yes'; dice sus tipos),transcribeSteps.excludes-voice-step(transcribeStepsdeja fuera uno de esos steps) ytranscribeSteps.noMatch(ningún tipo detranscribeStepsexiste en el plan: no se transcribe ningún step).transcribeSteps.unknownTypeahora 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 deface-modelospeechno trae ningún byte nuevo durantestallMs, 20 s por defecto; uno por atasco, constage,subStage,messageKeyyuserMessage; no corta nada),sttconreason: 'timeout'(se agotó el tope de la voz: la captura sigue sin voz),prepare.stale(una captura no pudo usar una parte preparada, conpart,fieldsyreason, y la carga ella),prepare.released(se liberó lo que cargóprepare(), con sureason, como'replaced','release','abort'o'pagehide'; desde la 0.43.0, conkeepPrepared, también'unusable'con supart: kodec dejó inservible una parte guardada mientras esperaba la siguiente captura, y solo se suelta esa parte) y, en modo grabación,recording.option-ignoredparastartup.timeouts.visionystartup.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', confaceReloaded: true) yface.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 uncodec.error. Una segunda pérdida en la misma captura, o una recarga que falla, la paran concapture-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 elcodecErrorsdel informe (SessionReport).no-audio-trackes informativo (lo tiene toda sesión en vivo sin transcripción);audio-start-failedpierde la transcripción. Desde la 0.43.0 (kodec 5.0.0-rc.14) no cuenta la recarga de la cara deface.context-lostyprepare.face-lost, ni un huecocapture-stalledque 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 decaptureBaseline(). 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.
Diferido, en el navegador
Sección titulada «Diferido, en el navegador»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).
Diferido, en tu backend
Sección titulada «Diferido, en tu backend»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.
Los errores HTTP de Engine
Sección titulada «Los errores HTTP de Engine»Engine contesta los errores con esta forma:
{ "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.
El 202 de la interpretación
Sección titulada «El 202 de la interpretación»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).
// 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 }}Lo que el SDK reintenta solo
Sección titulada «Lo que el SDK reintenta solo»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.
Soporte
Sección titulada «Soporte»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.