# Límites declarados y modos de fallo

## Lo que Engine no hace

- No infiere intención, no detecta engaño y no diagnostica. Las lecturas de bienestar son prediagnósticas.
- Los indicadores describen la interacción, no a la persona: "esta entrevista produjo rechazo en el minuto veinte", nunca "este candidato es una persona que rechaza".
- El arousal es intensidad expresiva, no activación fisiológica.

## Cuando la interpretación no sabe

El whitepaper declara cómo se comporta la interpretación en sus límites: "uncatalogued" cuando no encaja ningún caso, menos fiabilidad con una señal de baja calidad, solo calibración poblacional cuando no hay baseline personal, y sin citas cuando no hay corpus. Los resultados HTTP aún no exponen campos de fiabilidad ni de calibración.

## Límites técnicos

- Una captura completada por posición e inscripción: para volver a medir, vuelve a inscribir.
- Las duraciones de los steps son una guía: Engine no las aplica, pero el SDK avisa por defecto y puede rechazar (`stepDurations`, [Steps y marcado](/docs/es/sdk/steps/#la-comprobación-de-las-duraciones)).
- Los primeros segundos de una captura no tienen valor para los indicadores que se calculan sobre una ventana de frames, como workload.
- Una sesión que no recibe lotes durante un tiempo se abandona; el umbral es un ajuste del entorno.
- `results.ready` se envía una vez por posición, cuando su captura está completa, y no en todos los casos: sigue consultando `/results` como respaldo.
- Las capturas de Measurement no se interpretan.
- Lo que obtienes depende también de las condiciones de la persona ([Cómo capturar para la máxima precisión](/docs/es/concepts/capture/)) y del dispositivo ([Dispositivos, calidad y modo](/docs/es/start/devices-and-modes/)).

## Límites del SDK y del diferido

Lo que el SDK y tu backend añaden a los límites de Engine. No hay webhooks de resultados en el flujo del SDK: el único webhook es el del servicio de procesado, en diferido.

| Qué | Límite | Qué pasa |
| --- | --- | --- |
| `POST /token` por el proxy del SDK | 10 por minuto por IP, declarado por Engine; cachea el token | Si Engine responde 429, el proxy responde 503 `E_RATE_LIMITED` con `Retry-After`. |
| Cuerpo de una petición por el proxy | 16 MiB | El default de `createEngineProxy` (`maxBodyBytes`) desde `capture-server` 0.12.0; antes, 8 MiB. Desde el SDK 0.34.0 un lote en vivo lleva como mucho 3 MB de frames; un SDK anterior a 0.34.0 envía hasta unos 9,3 MB con cámara, así que delante de él admite al menos 10 MB. La pasarela de DevLab admite 10 MiB. Un cuerpo mayor recibe `413` `E_BODY_TOO_LARGE` antes de llegar a Engine. |
| Timeout del proxy por petición | 120 s | No corta los flujos de eventos. |
| Subidas abiertas por persona | 3 | Una más responde `E_TOO_MANY_OPEN`. |
| Tamaños de la subida | Inicio de 1 MiB, trozos de 2 MiB, vídeo de hasta 1 GiB | Tu receptor puede bajar el límite del vídeo (`maxBytes`). |
| Cola del procesado | 50 trabajos | Con más en espera, el servicio responde `E_QUEUE_FULL`; los trabajos van de uno en uno. |
| Ventana de las firmas (URL del token y webhook) | ±300 s | Un reloj de servidor desviado más se rechaza como firma mala. |
| Nonces guardados | 600 s | Un nonce repetido dentro de la ventana se rechaza como repetición. |
| Cuerpo del webhook | 1 MiB | Sin webhooks de resultados en el flujo del SDK: este es el webhook del servicio de procesado hacia tu backend. |
| Duración de los steps | `stepDurations`: `warn` (por defecto), `enforce` u `off` | Engine no impone la duración de los steps; el SDK avisa por defecto y, con `enforce`, rechaza con `E_STEP_DURATION`. |

## Fallos que aun así responden 2xx

| Hiciste | Engine responde | Qué pasa |
| --- | --- | --- |
| Omitiste `triggerAnalysis` en el último lote | `202` | No se pide interpretación. Con el SDK es al revés |
| Enviaste frames sin `featuresMeta` | `202`, `framesWithoutFeaturesMeta` mayor que 0 | Esos frames no dan los ejes de valencia ni de arousal |
| Enviaste frames con otro número de landmarks o de coeficientes | `202` | Landmarks: 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. Coeficientes: el frame se usa sin ellos |
| Te saltaste el `Final` de un step | `202` | El step nunca se cierra; la sesión se abandona |
| Dejaste un hueco en `kpnfile.order` | `202` hasta el `Final` | El `Final` responde `400` con `KPN-EMO-MISSING-PACKETS` y `missingOrders` (mira Códigos de calidad, más abajo) |
| Pediste los resultados antes de tiempo | `200` con `rawResults` y `aggResults` vacíos | Consulta en bucle hasta que la captura se complete |
| Escribiste mal un campo | `202` | El campo se ignora |
| Reenviaste un lote con otro contenido | `202` | Engine se queda con la primera copia |
| Enviaste el último lote del baseline con un hueco | `202` con `missingOrders` | No se calcula el baseline |
| Inscribiste a un usuario sin baseline | `201` con `baselineWarning` | Solo se aplica la calibración poblacional |
| Volviste a llamar a `/analyze` | `200`, `from_cache: true` | Recibes la interpretación guardada si su análisis salió completo; con `metadata.status` `degraded` o `failed`, Engine la regenera (`from_cache: false`), y eso cuesta tokens del modelo de lenguaje |
| Cancelaste sin ninguna captura abierta | `200`, `cancelled: false` | No hay nada que cancelar |

## Errores

| Código | Cuándo | Cuerpo |
| --- | --- | --- |
| `400` | JSON mal formado, o un campo con el tipo equivocado | Un cuerpo JSON con `code` y `message` (p. ej. `Field 'x' has an invalid value or type.`). No se procesó nada |
| `400` | Un lote rompe el contrato | `{ "code": 400, "message": "…", "qualityCode": "KPN-EMO-STEP" }` |
| `400` | `POST /user-protocols` no puede saber para cuál de tus contextos es la inscripción | `reason`: `CONTEXT_REQUIRED` o `CONTEXT_NOT_VALID` (abajo) |
| `401` | Falta el token o ha caducado | Vacío, con `WWW-Authenticate: Bearer` |
| `403` | Un usuario bloqueado | `{ "code": 403, "reason": "USER_BLOCKED", "message": "…" }` |
| `404` | Un id que no existe o no es tuyo | `{ "code": 404, "message": "Not found." }` |
| `409` | Reglas de sesión o de posición | `reason`: ver [Sesiones](/docs/es/concepts/sessions/) |
| `409` | `/analyze` sobre un protocolo que no se interpreta, como Measurement | `{ "code": 409, "reason": "PROTOCOL_NOT_ANALYSED", "message": "…", "hint": "…" }` |

```json
{ "status": 400, "empty": false }
```

```json
{ "status": 404, "body": { "code": 404, "message": "Not found." } }
```

### Motivos de error

Cuando un `202`, un `400`, un `403`, un `409` o un `422` lleva `reason`, decide por él; `message` y `hint` son para personas.

| `reason` | Estado | Qué pasó | Qué hacer |
| --- | --- | --- | --- |
| `USER_BLOCKED` | `403` | El usuario está bloqueado | Nada en las rutas de actividad hasta `POST /users/unblock` |
| `ANALYSIS_IN_PROGRESS` | `202` | `POST /analyze` mientras Engine ya analiza esa sesión (no con un solo `step`; la marca caduca a los 10 min) | No es un error: espera `constellation.complete` o vuelve a llamar pasados `retryAfterSeconds` (también en `Retry-After`) |
| `PROTOCOL_NOT_ANALYSED` | `409` | `/analyze` sobre un protocolo que no se interpreta, como Measurement | No llames a `/analyze` para él: lee los indicadores con `GET /results` |
| `MUST_START_AT_FIRST_POSITION` | `409` | Un protocolo con calendario empieza por su primera posición | Empieza por la posición de `goTo` |
| `MECHANIC_NOT_YET_AVAILABLE` | `409` | La posición aún no está abierta | Reintenta en `earliestAt`; de antemano, `window.earliestAt` en `nextSessions` (Engine del entorno de pruebas) |
| `MECHANIC_EXPIRED` | `409` | Su ventana se cerró para siempre | Sigue con `goTo` |
| `POSITION_ALREADY_COMPLETED` | `409` | Ya tiene una sesión completada | No recaptures; inscribe de nuevo para volver a medir |
| `SESSION_ABANDONED` | `409` | La captura se abandonó | Reinicia desde el step 1 con `kpnfile.order` 1 |
| `PROTOCOL_DEPRECATED` | `409` | El protocolo se retiró. Una captura ya en curso puede terminar | Inscribe en el de `publishedProtocolPid` (`null` si no hay). En un lote siempre es `null`: busca el sustituto en `GET /catalog/protocols` |
| `MECHANIC_DEPRECATED` | `409` | Esa mecánica se retiró | Lo medido se queda; no acepta capturas nuevas |
| `USER_PROTOCOL_RETIRED` | `409` | La inscripción se retiró para ese usuario | Sus resultados y `POST /analyze` siguen disponibles |
| `CONTEXT_NOT_ASSIGNED` | `409` | El protocolo ya no está disponible para tu organización | Sus resultados y `POST /analyze` siguen disponibles |
| `CONTEXT_REQUIRED` | `400` | `POST /user-protocols` de un protocolo que está en más de uno de tus contextos, sin `contextPid` | Repítela con `contextPid`: el `pid` en `GET /catalog/contexts` del contexto de esa inscripción. Hoy solo por la API HTTP: el SDK no envía `contextPid` |
| `CONTEXT_NOT_VALID` | `400` | `POST /user-protocols` con un `contextPid` que no es ninguno de tus contextos que incluya este protocolo | Tómalo de `pid` en `GET /catalog/contexts`, o no lo envíes si el protocolo está en uno solo de tus contextos |
| `POSITION_RESERVED` | `409` | Otro intento retiene la posición: una captura en curso o una grabación pendiente de enviar (`holder` dice cuál) | Pregunta a la persona; solo si lo confirma, repite `POST …/context` con `discardPending: true` |
| `CAPTURE_DISCARDED` | `409` | Esa grabación (`captureId`) se descartó | No reintentes |
| `CAPTURE_OUT_OF_ORDER` | `409` | Una grabación enviada después es anterior a la última sesión analizada de la persona en el mismo contexto | No reintentes: la respuesta no cambiará |
| `CAPTURE_CANCELLED` | `409` | El aviso de fin de una grabación (`recordingEndedAt` sin `capturedAt`) llegó después de cancelarla o de rechazarla por fuera de orden; no reserva nada | No reintentes |
| `CAPTURE_TOKEN_SCOPE` | `403` | Un token de captura (`POST /token/capture`) usado fuera de su captura: otra ruta, otra mecánica u otro `captureId` | Ahí, usa tu token normal; para otra captura, pide otro token de captura |
| `CAPTURE_TOKEN_RATE_LIMIT` | `429` | Solo con un token de captura: más peticiones en un minuto para esa captura que su límite (15 entre `GET …/schema` y `POST …/context`, 30 para `POST /process-kpn-emo`, 60 para el resto). No se procesó nada | Espera los segundos de `Retry-After` y repite la misma petición. Un token nuevo para el mismo `captureId` conserva la cuenta |
| `CAPTURE_ID_IN_USE` | `409` | `POST …/recordings` con un `captureId` que es de otra grabación | Usa un `captureId` nuevo |
| `ALREADY_UPLOADED` | `409` | `POST …/recordings` de una grabación ya subida | Nada: ya está subida |
| `UPLOAD_NOT_FOUND` | `409` | `POST …/recordings/{captureId}/complete` antes de que el vídeo esté en el almacenamiento | Termina el `PUT` a `uploadUrl` y vuelve a llamar |
| `NOT_UPLOADED` | `409` | `GET …/recordings/{captureId}/video` antes de que la grabación esté `uploaded` | Llama antes a `complete` y después pide la URL del vídeo |
| `SIZE_MISMATCH` | `409` | El vídeo subido no tiene el tamaño anunciado (`expectedBytes`, `actualBytes`) | Súbelo de nuevo con el tamaño anunciado, o anúncialo con un `captureId` nuevo |
| `STORAGE_UNAVAILABLE` | `503` | El almacenamiento de vídeo no está disponible; no se cambió nada | Reintenta en un momento |
| `TAXONOMY_INVALID` | `422` | `POST …/context` con ids de taxonomía que no cuadran. Hoy no se devuelve: el mismo caso responde `201` con `taxonomyWarnings`, cuyo `code` es, por ejemplo, `UNKNOWN_CONTEXT` (los `issues` del `422` usan códigos del mismo tipo, como `SUBCONTEXT_NOT_IN_CONTEXT`); el valor se guardó igualmente | Corrige los ids; prepara tu código para el `422` |

### Códigos de calidad

Un `400` de un lote puede llevar `qualityCode`: `KPN-EMO-STEP`, `KPN-EMO-MISSING-PACKETS` y `KPN-EMO-MEDIA` en `POST /process-kpn-emo`; un lote de microintervención (`POST /interruptions/{interruptionId}/process-kpn-emo`) puede devolver cualquiera de estos salvo `KPN-EMO-MEDIA`.

| `qualityCode` | Significado | ¿Reintentar? |
| --- | --- | --- |
| `KPN-EMO-STEP` | Ese `step` no está en el plan de la mecánica | Corrige el `step` |
| `KPN-EMO-MISSING-PACKETS` | Llegó el lote `Final` pero no lotes anteriores de su step; `missingOrders` los enumera, y ese `Final` no guardó nada | Sí: envía los lotes de `missingOrders` y después repite el `Final` |
| `KPN-EMO-STEP-TYPE` | Una mecánica de flujo libre sin tipo de step por defecto | No |
| `KPN-EMO-NO-PLAN` | Una mecánica de flujo fijo sin steps definidos | No |
| `KPN-EMO-MECHANIC` | La mecánica ofrecida no existe | No |
| `KPN-EMO-MEDIA` | `mediaId` no es un uuid, es un id numérico del catálogo, no existe o es de contenido de otra organización (la misma respuesta, antes de guardar nada) | Corrige `mediaId`: usa `steps[].media[].pid` del guion |
| `KPN-EMO-INTERRUPTION-CLOSED` | La interrupción está rechazada, completada o caducada | No |
