Límites declarados y modos de fallo
Lo que Engine no hace, los límites técnicos, los fallos que aun así responden 2xx y los cuerpos de error.
Lo que Engine no hace
Sección titulada «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
Sección titulada «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
Sección titulada «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). - 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.readyse envía una vez por posición, cuando su captura está completa, y no en todos los casos: sigue consultando/resultscomo 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) y del dispositivo (Dispositivos, calidad y modo).
Límites del SDK y del diferido
Sección titulada «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
Sección titulada «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
Sección titulada «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 |
409 |
/analyze sobre un protocolo que no se interpreta, como Measurement |
{ "code": 409, "reason": "PROTOCOL_NOT_ANALYSED", "message": "…", "hint": "…" } |
{ "status": 400, "empty": false }{ "status": 404, "body": { "code": 404, "message": "Not found." } }Motivos de error
Sección titulada «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
Sección titulada «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 |