# Timeouts

## 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

| 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

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](/docs/sdk/on-device/#the-startup-screen)). `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](/docs/guides/load-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](/docs/sdk/on-device/#the-startup-screen)). 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

| 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](/docs/concepts/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

- `/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](/docs/api/proxy/) use 300 seconds for the read timeout and no limit on the event streams.

## Long captures

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.

## 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](/docs/sdk/processing/#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](/docs/sdk/processing/#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. |
