# Errores, avisos y reintentos

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

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

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](#el-202-de-la-interpretación); 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](/docs/es/sdk/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`.

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

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](/docs/es/sdk/steps/).

- `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](/docs/es/sdk/on-device/#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](/docs/es/sdk/processing/#la-url-del-token)), 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](/docs/es/concepts/results/#un-índice-de-0-a-100).

- 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](/docs/es/guides/csp-transcription/).

- 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](/docs/es/sdk/on-device/#la-pantalla-de-arranque).

- 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](/docs/es/concepts/results/#interpretación-para-una-audiencia)).

Más en [En el dispositivo](/docs/es/sdk/on-device/#errores-y-avisos).

## 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)](/docs/es/sdk/deferred/).

## 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](/docs/es/sdk/processing/#códigos-de-error).

## Los errores HTTP de Engine

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](/docs/es/concepts/limits/#motivos-de-error).

### 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](/docs/es/api/proxy/)).

```js
// 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

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

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.
