Ir al contenido
DevLab

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.

En esta página
  1. Lo que Engine no hace
  2. Cuando la interpretación no sabe
  3. Límites técnicos
  4. Límites del SDK y del diferido
  5. Fallos que aun así responden 2xx
  6. Errores
  7. Motivos de error
  8. Códigos de calidad
  • 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.

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.

  • 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.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) y del dispositivo (Dispositivos, calidad y modo).

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.

Límites del SDK y del diferido
QuéLímiteQué pasa
POST /token por el proxy del SDK10 por minuto por IP, declarado por Engine; cachea el tokenSi Engine responde 429, el proxy responde 503 E_RATE_LIMITED con Retry-After.
Cuerpo de una petición por el proxy16 MiBEl 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ón120 sNo corta los flujos de eventos.
Subidas abiertas por persona3Una más responde E_TOO_MANY_OPEN.
Tamaños de la subidaInicio de 1 MiB, trozos de 2 MiB, vídeo de hasta 1 GiBTu receptor puede bajar el límite del vídeo (maxBytes).
Cola del procesado50 trabajosCon 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 sUn reloj de servidor desviado más se rechaza como firma mala.
Nonces guardados600 sUn nonce repetido dentro de la ventana se rechaza como repetición.
Cuerpo del webhook1 MiBSin webhooks de resultados en el flujo del SDK: este es el webhook del servicio de procesado hacia tu backend.
Duración de los stepsstepDurations: warn (por defecto), enforce u offEngine no impone la duración de los steps; el SDK avisa por defecto y, con enforce, rechaza con E_STEP_DURATION.
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
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": "…" }
JSON
{ "status": 400, "empty": false }
JSON
{ "status": 404, "body": { "code": 404, "message": "Not found." } }

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

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