Timeouts
How long the SDK, Engine and your proxy wait, and how to stack them so the right layer reports the problem.
The short version
Section titled “The short version”| 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.
The SDK
Section titled “The SDK”| 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.
The startup
Section titled “The startup”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.
Engine
Section titled “Engine”| 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 |
Your proxy
Section titled “Your proxy”/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 makesstop()fall back toPOST /analyze(interpretation.sse-timeout)./analyze/streamand/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_MSis 120 seconds, butANALYZE_TIMEOUT_MS(the interpretation) is 300 seconds.
The proxy examples use 300 seconds for the read timeout and no limit on the event streams.
Long captures
Section titled “Long captures”The longer a step, the longer Engine takes to close the position after the last Final:
- raise
outcomeDeadlineMsin the SDK, or pollGET /results/{up}/{pm}for longer over HTTP; - keep
userProtocolIdandprotocolMechanicIdon your side, so you can read the results and the interpretation later if the page closes; E_RESULTS_TIMEOUTdoes not mean the capture was lost: read the results later instead of capturing again.
Deferred
Section titled “Deferred”The upload, the processing service and your receiver have their own timeouts and windows:
| What | Default | What to know |
|---|---|---|
| Each upload attempt | 60 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 s | It 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 s | Past it, complete answers 503 E_NOTIFY_FAILED; your onComplete does not stop. |
Waiting for the lock on a capture (lockWaitMs) | 45 s | Past it, 503 E_BUSY. |
A complete in the worst case | about 85 s | The sum of the two: a gateway with a 60 s timeout may answer 504 first. |
| Minting a token | 20 s | Past it, E_MINT_TIMEOUT. |
| Each call to the processing service | 30 s | submit, getJob and retry are bounded. |
| A processing job | 60 s without a heartbeat, 120 min in total | Then it fails with its errorCode; see Error codes. |
Results in the replay (outcomeDeadlineMs) | 600 s | On-device the default is 240 s. |
Waiting for the interpretation (interpreting) | 300 s | In flight: the job never ends failed here. Past it, succeeded with interpretation: timeout; see The interpretation. |
| The signed URL of the video | 24 h | An expired one fails with E_VIDEO_URL_EXPIRED: retry with a new URL. |
| An unconfirmed upload in your receiver | 72 h | receiver.sweep() deletes it; a confirmed video never expires on its own. |