Skip to content
DevLab

Timeouts

How long the SDK, Engine and your proxy wait, and how to stack them so the right layer reports the problem.

On this page
  1. The short version
  2. The SDK
  3. The startup
  4. Engine
  5. Your proxy
  6. Long captures
  7. Deferred
Layer Set it to
Your proxy, read timeout 300 seconds, with no buffering and no total limit on the two event streams
SDK analyzeTimeoutMs 280 seconds (the default)
SDK outcomeDeadlineMs 240 seconds (the default); raise it for long captures
Your HTTP client, blocking POST /analyze At least 180 seconds

The SDK gives up before your proxy does, so a slow interpretation reaches your code as E_INTERPRETATION_TIMEOUT, with a code you can handle, instead of a cut connection. Keep that order: SDK first, then your proxy.

What Default Option
Any HTTP request 15 s requestTimeoutMs
One batch of frames, with retries up to 30 s; 3 attempts (2 for the Final), waiting 0.5, 1 and 2 s —
Sending a whole step 90 s —
Pause before the Final of each step 2.5 s —
First frame from the camera 15 s —
Closing the position after the last Final (E_RESULTS_TIMEOUT) 240 s; only a longer value is accepted outcomeDeadlineMs
Polling attempts and results while closing every 3 s —
Waiting for the interpretation in stop(): Engine’s notice on the stream, then one POST /analyze with the same limit (E_INTERPRETATION_TIMEOUT); since 0.44.0, after a 202 ANALYSIS_IN_PROGRESS it waits what Engine asks and asks again within the same limit, counted from the first 202 (E_ANALYSIS_IN_PROGRESS) 280 s; at least 180 s; 120 s for the notice if the stream never connected analyzeTimeoutMs
The transcription queue when closing 20 s —
Reconnecting the live stream after 0.5, 1, 2, 5 and 10 s; warns stream.unavailable after 3 drops without connecting —
The token renewed 5 s before expiresAt; without it, after a 401 your token endpoint
The baseline 30 s, from 1 to 60 s durationMs

stop() waits for the interpretation (since 0.38.0): first for Engine’s notice, up to analyzeTimeoutMs, and, if it does not arrive, for one POST /analyze, which serves the stored one. Since 0.44.0, if that /analyze answers 202 ANALYSIS_IN_PROGRESS (Engine is still generating it), the SDK waits what Engine asks (30 s when it does not say), keeps listening for the notice and asks again, all within analyzeTimeoutMs counted from the first 202; if that runs out it ends with E_ANALYSIS_IN_PROGRESS (recoverable: the results were delivered, read the interpretation later with client.analyze()) instead of E_INTERPRETATION_TIMEOUT. In the worst case it adds up outcomeDeadlineMs (the close), analyzeTimeoutMs (the wait) and analyzeTimeoutMs again (the /analyze, or the wait after its 202, which answers at once): about 13 minutes with the defaults. Show the indicators while it waits. onInterpretationDetails arrives right after the narrative, so you can store both together; only with interpretation: 'stream' do the details come later, after stop() has resolved, and then you wait for them with a deadline of your own.

Since 0.42.0 the load between the click and the first step has caps of its own, in startup.timeouts of the client (On-device). null removes a cap; leaving a key out keeps its default.

What Default Option When it runs out
The face model, from the camera being granted 120 s startup.timeouts.vision.totalMs CaptureStartError with stage: 'face-model' and reason: 'timeout'; the camera is switched off and the pair is free
The whole speech startup (the wait for the video, the pre-check and the load) 600 s startup.timeouts.speech.totalMs The stt warning with reason: 'timeout'; the capture goes on without speech
A download that brings no new byte 20 s startup.timeouts.vision.stallMs, startup.timeouts.speech.stallMs The startup.stalled warning; it cuts nothing
The speech pre-check and the device diagnosis 5 s startup.timeouts.gateMs What did not answer stays unknown; raising it lengthens the startup

The camera permission, the orientation wait and your token endpoint have no cap: they depend on the person or on you, and the capture’s signal cancels them. With the defaults, the face model is cut below about 0.9 Mbps (about 13.5 MB) and speech below about 2.1 Mbps (about 160 MB). When a cap runs out, part of the load may go on in the background (the import of the vision module, the creation of the face model, a speech load without a worker): a retry on the same page waits for it. client.prepare() takes the same caps, and its timeouts changes them for that call only; moving the load to before Start: Load the models. With no frame in 15 s the start fails with CaptureStartError (stage: 'first-frame', reason: 'timeout'); since 0.42.1 its message depends on the source: first-frame.timeout with the webcam, first-frame.timeout-media with your own stream or <video> (On-device). Since 0.43.0, when kodec has to load the face again (prepare.face-lost, face.context-lost), the first-frame wait starts over once, for startup.timeouts.vision.totalMs; once the capture has its first frame, that reload is bounded by the same cap (120 s by default, and 120 s when it is null), and past it the capture fails with capture-failed.

What Value
The token expiresIn seconds, currently 3600: read the field
A session without batches abandoned after a time set per environment; the message tells you how long (see Sessions)
/stream/{up} a : ping comment every 30 seconds; closed with stream.end after a period without events, set per environment. Reconnecting is allowed
/stream/{up} when the credential changes closed with stream.end and a reason: credential_expired, credential_revoked, credential_deleted, credential_rotated or credential_scope_changed (Neurologyca changed the key’s scope). Reconnecting with the same token is refused: mint a new token with a valid API key
/analyze/stream no ping of its own: the first event can take close to a minute. The SDK opens it only with interpretation: 'stream'
The interpretation usually takes tens of seconds and can take about two minutes end to end; reading a stored one takes under a second
Closing a long capture grows with the number of frames: 128 s were measured for a step of 5,888 frames
  • /stream/{up}: a read timeout above 30 seconds (the ping) and no total limit. The SDK waits for the interpretation on it, so a proxy that cuts it makes stop() fall back to POST /analyze (interpretation.sse-timeout).
  • /analyze/stream and /analyze: a read timeout of at least 180 seconds, because nothing arrives while the interpretation is generated.
  • Everything else: 300 seconds is plenty.
  • The server SDK’s proxy: PROXY_TIMEOUT_MS is 120 seconds, but ANALYZE_TIMEOUT_MS (the interpretation) is 300 seconds.

The proxy examples use 300 seconds for the read timeout and no limit on the event streams.

The longer a step, the longer Engine takes to close the position after the last Final:

  • raise outcomeDeadlineMs in the SDK, or poll GET /results/{up}/{pm} for longer over HTTP;
  • keep userProtocolId and protocolMechanicId on your side, so you can read the results and the interpretation later if the page closes;
  • E_RESULTS_TIMEOUT does not mean the capture was lost: read the results later instead of capturing again.

The upload, the processing service and your receiver have their own timeouts and windows:

Deferred: timeouts and retention windows
WhatDefaultWhat to know
Each upload attempt60 s; a part, 60 s plus partBytes at 16 KiB/s (about 188 s with 2 MiB)The SDK retries with Retry-After.
complete (the last call of the upload)120 sIt can take about 85 s: a proxy in front with a 60 s read timeout cuts it. Give it more than 90 s.
Your onComplete (onCompleteTimeoutMs)40 sPast it, complete answers 503 E_NOTIFY_FAILED; your onComplete does not stop.
Waiting for the lock on a capture (lockWaitMs)45 sPast it, 503 E_BUSY.
A complete in the worst caseabout 85 sThe sum of the two: a gateway with a 60 s timeout may answer 504 first.
Minting a token20 sPast it, E_MINT_TIMEOUT.
Each call to the processing service30 ssubmit, getJob and retry are bounded.
A processing job60 s without a heartbeat, 120 min in totalThen it fails with its errorCode; see Error codes.
Results in the replay (outcomeDeadlineMs)600 sOn-device the default is 240 s.
Waiting for the interpretation (interpreting)300 sIn flight: the job never ends failed here. Past it, succeeded with interpretation: timeout; see The interpretation.
The signed URL of the video24 hAn expired one fails with E_VIDEO_URL_EXPIRED: retry with a new URL.
An unconfirmed upload in your receiver72 hreceiver.sweep() deletes it; a confirmed video never expires on its own.