Timeouts
Cuánto esperan el SDK, Engine y tu proxy, y cómo escalonarlos para que el problema lo informe la capa correcta.
En resumen
Sección titulada «En resumen»| Capa | Ponla en |
|---|---|
| Tu proxy, timeout de lectura | 300 segundos, sin buffering y sin límite total en los dos streams de eventos |
SDK analyzeTimeoutMs |
280 segundos (por defecto) |
SDK outcomeDeadlineMs |
240 segundos (por defecto); súbelo para capturas largas |
Tu cliente HTTP, POST /analyze bloqueante |
Al menos 180 segundos |
El SDK se rinde antes que tu proxy, así que una interpretación lenta llega a tu código como E_INTERPRETATION_TIMEOUT, con un código que puedes tratar, en lugar de una conexión cortada. Mantén ese orden: primero el SDK, después tu proxy.
| Qué | Por defecto | Opción |
|---|---|---|
| Cualquier petición HTTP | 15 s | requestTimeoutMs |
| Un lote de frames, con reintentos | hasta 30 s; 3 intentos (2 para el Final), con esperas de 0,5, 1 y 2 s |
— |
| Enviar un step entero | 90 s | — |
Pausa antes del Final de cada step |
2,5 s | — |
| Primer frame de la cámara | 15 s | — |
Cierre de la posición tras el último Final (E_RESULTS_TIMEOUT) |
240 s; solo se acepta un valor mayor | outcomeDeadlineMs |
| Sondeo de intentos y resultados al cerrar | cada 3 s | — |
La espera de la interpretación en stop(): el aviso de Engine en el stream y después un POST /analyze con el mismo límite (E_INTERPRETATION_TIMEOUT); desde la 0.44.0, tras un 202 ANALYSIS_IN_PROGRESS espera lo que pide Engine y vuelve a pedirla dentro del mismo límite, contado desde el primer 202 (E_ANALYSIS_IN_PROGRESS) |
280 s; al menos 180 s; 120 s para el aviso si el stream nunca conectó | analyzeTimeoutMs |
| La cola de la transcripción al cerrar | 20 s | — |
| Reconexión del stream en vivo | tras 0,5, 1, 2, 5 y 10 s; avisa stream.unavailable tras 3 cortes sin conectar |
— |
| El token | se renueva 5 s antes de expiresAt; sin él, tras un 401 |
tu endpoint de token |
| El baseline | 30 s, de 1 a 60 s | durationMs |
stop() espera la interpretación (desde 0.38.0): primero el aviso de Engine, hasta analyzeTimeoutMs, y, si no llega, un POST /analyze, que sirve la guardada. Desde la 0.44.0, si ese /analyze responde 202 ANALYSIS_IN_PROGRESS (Engine aún la está generando), el SDK espera lo que pide Engine (30 s si no lo dice), sigue escuchando el aviso y vuelve a pedirla, todo dentro de analyzeTimeoutMs contado desde el primer 202; si se agota, acaba con E_ANALYSIS_IN_PROGRESS (recuperable: los resultados llegaron, lee la interpretación más tarde con client.analyze()) en vez de E_INTERPRETATION_TIMEOUT. En el peor caso suma outcomeDeadlineMs (el cierre), analyzeTimeoutMs (la espera) y otra vez analyzeTimeoutMs (el /analyze, o la espera tras su 202, que responde enseguida): unos 13 minutos con los valores por defecto. Enseña los indicadores mientras espera. onInterpretationDetails llega justo después de la narrativa, así que puedes guardar las dos juntas; solo con interpretation: 'stream' el detalle llega más tarde, cuando stop() ya ha resuelto, y entonces lo esperas con un plazo propio.
El arranque
Sección titulada «El arranque»Desde la 0.42.0, la carga entre el clic y el primer step tiene sus propios topes, en startup.timeouts del cliente (En el dispositivo). null quita un tope; sin la clave, queda el valor por defecto.
| Qué | Por defecto | Opción | Cuando se agota |
|---|---|---|---|
| El modelo de la cara, desde que se concede la cámara | 120 s | startup.timeouts.vision.totalMs |
CaptureStartError con stage: 'face-model' y reason: 'timeout'; se apaga la cámara y el par queda libre |
| Todo el arranque de la voz (la espera del vídeo, la comprobación previa y la carga) | 600 s | startup.timeouts.speech.totalMs |
El aviso stt con reason: 'timeout'; la captura sigue sin voz |
| Una descarga que no trae ningún byte nuevo | 20 s | startup.timeouts.vision.stallMs, startup.timeouts.speech.stallMs |
El aviso startup.stalled; no corta nada |
| La comprobación previa de la voz y el diagnóstico del dispositivo | 5 s | startup.timeouts.gateMs |
Lo que no respondió queda unknown; subirlo alarga el arranque |
El permiso de la cámara, la espera de la orientación y tu endpoint de token no tienen tope: dependen de la persona o de ti, y el signal de la captura los cancela. Con los valores por defecto, el modelo de la cara se corta por debajo de unos 0,9 Mbps (unos 13,5 MB) y la voz por debajo de unos 2,1 Mbps (unos 160 MB). Cuando se agota un tope, parte de la carga puede seguir en segundo plano (la importación del módulo de visión, la creación del modelo de la cara, una carga de la voz sin worker): un reintento en la misma página la espera. client.prepare() usa los mismos topes, y su timeouts los cambia solo para esa llamada; para llevar la carga a antes de Empezar: Cargar los modelos. Sin ningún frame en 15 s, el arranque falla con CaptureStartError (stage: 'first-frame', reason: 'timeout'); desde la 0.42.1 su mensaje depende de la fuente: first-frame.timeout con la webcam, first-frame.timeout-media con tu propio stream o <video> (En el dispositivo). Desde la 0.43.0, cuando kodec tiene que volver a cargar la cara (prepare.face-lost, face.context-lost), la espera del primer frame vuelve a empezar una vez, con startup.timeouts.vision.totalMs; con la captura ya en su primer frame, esa recarga tiene el mismo tope (120 s por defecto, y 120 s cuando es null), y pasado, la captura falla con capture-failed.
| Qué | Valor |
|---|---|
| El token | expiresIn segundos, hoy 3600: lee el campo |
| Una sesión sin lotes | se abandona tras un tiempo que fija cada entorno; el mensaje te dice cuánto (ver Sesiones) |
/stream/{up} |
un comentario : ping cada 30 segundos; se cierra con stream.end tras un periodo sin eventos que fija cada entorno. Se puede reconectar |
/stream/{up} cuando cambia la credencial |
se cierra con stream.end y un reason: credential_expired, credential_revoked, credential_deleted, credential_rotated o credential_scope_changed (Neurologyca cambió el scope de la key). Con el mismo token no se puede reconectar: acuña uno nuevo con una API key válida |
/analyze/stream |
sin ping propio: el primer evento puede tardar cerca de un minuto. El SDK solo lo abre con interpretation: 'stream' |
| La interpretación | suele tardar decenas de segundos y puede tardar unos dos minutos de punta a punta; leer una guardada tarda menos de un segundo |
| El cierre de una captura larga | crece con el número de frames: se midieron 128 s para un step de 5.888 frames |
Tu proxy
Sección titulada «Tu proxy»/stream/{up}: un timeout de lectura por encima de 30 segundos (el ping) y sin límite total. El SDK espera en él la interpretación, así que un proxy que lo corta hace questop()recurra aPOST /analyze(interpretation.sse-timeout)./analyze/streamy/analyze: un timeout de lectura de al menos 180 segundos, porque no llega nada mientras se genera la interpretación.- Todo lo demás: 300 segundos sobran.
- El proxy del SDK de servidor:
PROXY_TIMEOUT_MSes de 120 segundos, peroANALYZE_TIMEOUT_MS(la interpretación) es de 300 segundos.
Los ejemplos de proxy usan 300 segundos de timeout de lectura y ningún límite en los streams de eventos.
Capturas largas
Sección titulada «Capturas largas»Cuanto más largo es un step, más tarda Engine en cerrar la posición tras el último Final:
- sube
outcomeDeadlineMsen el SDK, o sondeaGET /results/{up}/{pm}durante más tiempo por HTTP; - guarda
userProtocolIdyprotocolMechanicIden tu lado, para poder leer los resultados y la interpretación más tarde si la página se cierra; E_RESULTS_TIMEOUTno significa que la captura se perdiera: lee los resultados más tarde en lugar de capturar de nuevo.
Diferido
Sección titulada «Diferido»La subida, el servicio de procesado y tu receptor tienen sus propios timeouts y ventanas:
| Qué | Por defecto | Qué saber |
|---|---|---|
| Cada intento de subida | 60 s; una parte, 60 s más partBytes a 16 KiB/s (unos 188 s con 2 MiB) | El SDK reintenta con Retry-After. |
complete (la última llamada de la subida) | 120 s | Puede tardar unos 85 s: un proxy delante con 60 s de lectura lo corta. Dale más de 90 s. |
Tu onComplete (onCompleteTimeoutMs) | 40 s | Pasado ese tiempo, complete responde 503 E_NOTIFY_FAILED; tu onComplete no se detiene. |
Espera al cerrojo de una captura (lockWaitMs) | 45 s | Pasado ese tiempo, 503 E_BUSY. |
Un complete en el peor caso | unos 85 s | La suma de las dos: una pasarela con 60 s de timeout puede responder 504 antes. |
| Acuñar un token | 20 s | Pasado ese tiempo, E_MINT_TIMEOUT. |
| Cada llamada al servicio de procesado | 30 s | submit, getJob y retry tienen tope. |
| Un trabajo de procesado | 60 s sin latido, 120 min en total | Después falla con su errorCode; ver Códigos de error. |
Resultados en la repetición (outcomeDeadlineMs) | 600 s | En el dispositivo, el valor por defecto es 240 s. |
La espera de la interpretación (interpreting) | 300 s | En curso: el trabajo nunca acaba failed aquí. Pasado ese tiempo, succeeded con interpretation: timeout; ver La interpretación. |
| La URL firmada del vídeo | 24 h | Una caducada falla con E_VIDEO_URL_EXPIRED: reintenta con una URL nueva. |
| Una subida sin confirmar en tu receptor | 72 h | receiver.sweep() la borra; un vídeo confirmado nunca caduca solo. |