# Errors, warnings and retries

## The rule that cost an incident

A `recoverable` other than `true` during the steps means the capture is lost: call `abort()`; after `stop()`, do not: codes such as `E_RESULTS_TIMEOUT` or `E_INTERPRETATION_TIMEOUT` also arrive with `recoverable: false`, but Engine already has the capture, and aborting there would destroy it.

## Three families

Pipeline failures arrive by `onError` (`{ code, message, recoverable, stepOrder? }`). Usage errors are thrown to the caller (classes that extend `ProtocolUsageError`, with a `code`). Warnings arrive by `onWarning` (`{ code, message, stepOrder? }`) and never stop the capture.

## On-device

The pipeline codes of `onError` (the published `ProtocolErrorCode`):

| Code | What it means | What to do |
| --- | --- | --- |
| `E_HTTP` | `GET /results` failed repeatedly at the transport level | Almost always the proxy or the network. Keep the pair and read the results later |
| `E_RESULTS_TIMEOUT` | No completed attempt within `outcomeDeadlineMs` (240 s by default). Not a loss: Engine accepted the capture and is still processing it | Do not recapture. Recover it with `client.retrieveResults(userProtocolId, protocolMechanicId)` (or `admin.getResults` from your backend): keep those two ids outside the tab. For long captures, raise `outcomeDeadlineMs` |
| `E_RESULTS_EMPTY` | The attempt completed and `/results` stayed empty | A real failure: save the pair and report it |
| `E_INTERPRETATION_TIMEOUT` | There were indicators but no interpretation: Engine's notice did not arrive on the event stream (or, with `interpretation: 'stream'`, the stream went quiet) and `/analyze` did not give it. Since 0.44.0 a `202` (`ANALYSIS_IN_PROGRESS`) no longer ends here: see `E_ANALYSIS_IN_PROGRESS` | Do not abort. Show the indicators and ask for the interpretation later (`client.analyze()` or `admin.analyze()`), or wait for `constellation.complete` |
| `E_ANALYSIS_IN_PROGRESS` | Since 0.44.0, with `recoverable: true` and status `timeout`. At the close, `/analyze` answered `202 ANALYSIS_IN_PROGRESS` (an analysis of the session was already running): the SDK waited what Engine asked (30 s when it does not say, never less than 1 s), still listening for Engine's notice, and asked again, within `analyzeTimeoutMs` counted from the first `202`; the wait ran out with Engine still writing it. Since 0.45.0 it also ends here when a repeated `/analyze` gets no answer at all, and the close ends at most about 10 s past that bound | Nothing is lost: the results were delivered. Show them, say the interpretation is still being written, and read it later with `client.analyze()` (or `admin.analyze()` from your backend), [as below](#the-202-of-the-interpretation); or raise `analyzeTimeoutMs` |
| `E_PROCESSING` | Engine reported a processing error (the message says the category) | The session is invalidated. Partial results are still emitted if some attempt managed to complete |
| `E_FRAMES_DISCARDED` | `kpi_source=frames_discarded`: the interpretation service discarded all the frames and analysed from aggregates. It comes back as a `200` | Almost always the number of landmarks. Check the kodec version: 478 are expected (468 face + 10 iris). With 468, measured on 2026-08-09, Engine accepted every batch and the session never closed; a frame with no face (`landmarks: []`) has not been measured |
| `E_UPLOAD_FAILED` | A partial batch upload failed and the SDK stopped sending. A 4xx (for example a `413` from your proxy) is terminal at the first try; a 5xx or network error is retried first (3 tries, 30 s) | The session is left invalid. A `413` means your proxy's body limit is too low ([Your backend](/docs/sdk/backend/)); otherwise retry when the pair is free |
| `E_STEP_LOST` | The `Final` of a step died with no way to know whether the server marked it. The SDK does not retry it, on purpose: a late packet on a session that is already complete creates a zombie session that blocks the pair | The session is lost. Wait for the sweep to free the pair (about 5 min, marked `abandoned`) and retry |
| `E_CAPTURE_LOST` | The camera's video track ended with the session alive (camera unplugged or permission withdrawn). Only with `{ type: 'webcam' }`. It invalidates the session even if no step was open | `abort()` and capture again |
| `E_RECORDING_LOST` | The recording was lost with the session alive: the camera's video track ended, the recorder failed or the device could not store a chunk | Nothing is delivered. Call `abort()` (it releases the reservation) and record again |
| `E_AXES_MISSING` | The analysis was refused because a Circumplex axis is missing. Almost certainly your frames lack `featuresMeta`; it only happens with a frame source of your own. Not emitted today (SDK 0.45.0): that case arrives as `E_TAXONOMY_REJECTED` | Do not recapture: the indicators are stored, ask for the interpretation again. Check that every frame carries `featuresMeta` |
| `E_NARRATIVE_REJECTED` | The narrative of the person (`voice` or `depth`) was refused after the capture; Engine accepts any value with a `200`. Not emitted today (SDK 0.45.0): that case arrives as `E_TAXONOMY_REJECTED` | Fix it on the person (`voice`: second or third; `depth`: standard or professional) and ask for the interpretation again. Do not recapture |
| `E_TAXONOMY_REJECTED` | A `422` from `/analyze`. Today every `422` arrives here, whatever its cause: Engine no longer sends the interpretation service's detail, and the SDK (0.45.0 too) sorts them by that text. So it also covers the cases of `E_AXES_MISSING`, `E_NARRATIVE_REJECTED` and `E_TENANT_UNKNOWN`, and its causes have opposite fixes | Check before recording anyone again. A frame source of your own: every frame carries `featuresMeta`. The person: `voice` and `depth` are valid. The id: if it is wrong for the protocol, the taxonomy freezes at capture time, so recapture with the right one. If it all matches, it is fixed without recapturing (ask Neurologyca) and `/analyze` on the same pair works afterwards |
| `E_TENANT_UNKNOWN` | The interpretation service has no active record of your organization. The credential was accepted. Not emitted today (SDK 0.45.0): that case arrives as `E_TAXONOMY_REJECTED` | Do not recapture: it is neither the capture nor the taxonomy. Ask Neurologyca; once it is fixed, ask for the interpretation again |
| `E_ANALYSIS_FAILED` | The analysis came back as failed: its interpretation is a placeholder, with a `200` | Do not show it as a result. The reason is in the `warnings` at the root of the payload. The indicators are still valid |
| `E_CONFLICT` | A `409` from Engine | Read `reason` and `conflict.<field>` |

`E_CONFLICT` comes with `reason` and `conflict` (`expired`, `goToPosition`, `earliestAt`, `expected`, `rule`, `hint`, `holder`, `captureId`). The eleven reasons (`CONFLICT_REASONS`):

- `SESSION_ABANDONED`: the capture was abandoned. Start again from step 1.
- `POSITION_ALREADY_COMPLETED`: the position already has a completed session. Do not capture again.
- `MECHANIC_EXPIRED`: its window closed for good. Continue with `conflict.goToPosition`.
- `MECHANIC_NOT_YET_AVAILABLE`: the position is not open yet. Try again at `conflict.earliestAt`.
- `MUST_START_AT_FIRST_POSITION`: a protocol with a schedule starts at its first position. Start with `conflict.goToPosition`.
- `PROTOCOL_DEPRECATED`: the protocol was retired. Use the one that replaces it.
- `POSITION_RESERVED`: another attempt holds the position (`conflict.holder`). Ask the person before discarding it.
- `CAPTURE_DISCARDED`: that recording was discarded. Do not retry.
- `CAPTURE_OUT_OF_ORDER`: the recording is older than the person's latest analysed session. Do not retry.
- `PROTOCOL_NOT_ANALYSED` (since 0.28.0): `/analyze` on a protocol that is not interpreted, such as Measurement. The indicators already arrived; what is missing is an interpretation. Since 0.29.0 the SDK does not ask for an analysis when Engine says `interpreted: false`, and if this 409 arrives anyway (an Engine that does not return `interpreted`), the session ends `complete` with its indicators: it is the normal end. `client.analyze()` on such a protocol still throws it.
- `CAPTURE_CANCELLED` (since 0.29.0, recording only): the end notice of a recording whose reservation was already cancelled (or closed as `CAPTURE_OUT_OF_ORDER`). The SDK does not retry it, says so once with `recording.end-notice-failed` and delivers the recording anyway: processing it reserves the position again.

The SDK also raises three warnings about the conflict itself (`CONFLICT_WARNINGS`): `conflict.unknown-reason` (a `reason` this version does not know: `reason` is a string, so branch on it with a default), `conflict.ambiguous-goto` and `conflict.earliestAt-assumed-utc`.

### Usage errors

They are thrown to your code, before or between steps, never by `onError`:

| Code | When |
| --- | --- |
| `E_STEP_SEQUENCE` | A step is started or ended out of the plan's order |
| `E_STEP_DURATION` | A step ended outside its window, with `stepDurations: 'enforce'` |
| `E_PLAN_INCOMPLETE` | `stop()` with steps of the plan still missing |
| `E_SESSION_DIRTY` | The pair already has an unfinished attempt |
| `E_CADENCE_BLOCKED` | The position is not available yet (`availableAt` says when) |
| `E_SESSION_INVALID` | The session was invalidated by an earlier error, or the source ended: call `abort()` |
| `E_MEDIA_UNKNOWN` | A `mediaPid` that is not in the step |
| `E_CAPTURE` | `CaptureStartError`: the capture could not start. Since 0.42.0 it always carries `stage` and `reason`: `'face-model'` (`'timeout'`: the face model cap, `startup.timeouts.vision.totalMs`, 120 s, ran out, and `subStage` says where; `'error'`: the load failed), `'first-frame'` (`'timeout'`: 15 s with no frame; `messageKey` `first-frame.timeout` with the webcam and, since 0.42.1, `first-frame.timeout-media` with your own `stream` or `<video>` and in a replay) or `'source'` (`'paused'` or `'metadata'`: the `<video>`; `'error'`: the source cannot be used), and `userMessage`. Since 0.43.0 (kodec 5.0.0-rc.14) a source that has already ended when the capture starts (a stopped stream track, a device that went away, a `<video>` that ended) fails at once, before any model loads, with `stage: 'source'` and `reason: 'error'`, with no `E_CAPTURE_LOST` and no `codec.error`: rewind your `<video>` before `captureProtocol`. A webcam that stops sending video while the capture starts fails the same way. And `'first-frame'` with `'error'` and the key `first-frame.face-reload-failed`: the face analysis stopped as the capture started and loading it again failed. After `subStage: 'vision-runtime'` offer a reload, not a retry. A denied `getUserMedia` arrives as the browser's `DOMException`, not as this code |
| `E_TAXONOMY_INVALID` | A `situationId` with no `hciId`; checked before opening the camera |
| `E_CADENCE_UNKNOWN` | Like `E_CADENCE_BLOCKED`, when the SDK cannot tell when the position opens |
| `E_FLOW_UNSUPPORTED` | The `flowMode` of the mechanic is not supported |
| `E_EMPTY_STEP` | A step closed without a single frame |
| `E_BASELINE_REQUEST` | Thrown by `client.captureBaseline()`: an invalid `durationMs` or `userId`, a second capture of the same user in flight, or the server rejecting the request |
| `E_BASELINE_INCOMPLETE` | `captureBaseline()` went well but packets are missing (`missingOrders`): no retry is possible, repeat the whole capture |
| `E_UNKNOWN_OPTION` | An option the SDK does not know; it throws before it touches the camera. Since 0.42.0 `createProtocolClient` throws it too for an unknown key (also inside `startup`), as `createRecordingClient` already did; before, it ignored it. The message says where an option of each capture (`signal`, `captureId`) goes. It also comes from `prepare({ models: { speech: true } })` on a client without the SDK's own transcription, and from `cacheStatus()` on a client in record mode |
| `E_CAPTURE_ABORTED` | `CaptureAbortedError` (since 0.42.0): you cancelled the startup with the `signal` of `captureProtocol` or `captureBaseline`. The camera, the microphone and the pair are released first; `stage` says where it was and `userMessage` carries the `capture.aborted` message. Not a camera failure |
| `E_PREPARE` | `PrepareError` (since 0.42.0), from `client.prepare()`: with `throwOnFailure: true`, a preparation that ended `'failed'` or `'aborted'` (`reason`, and the whole `PrepareResult` in `result`); and always, with `reason: 'capture-in-progress'` and `result: null`, while a capture or a baseline of this client is running. Prepare before, or once it ends |

### Warnings worth showing

The codes of `onWarning` are strings, not a published union: branch with a default case. The ones to show or log:

- `source.ended`: your file or stream is over; the open step closes.

- `step.duration-below-min`, `step.duration-above-max` and `step.media-undeclared`: see [Steps and marking](/docs/sdk/steps/).

- `capture.throttled` is relative to the session's own rate: it fires when the rate falls to a quarter of that session's own for three windows in a row, with a step open (once per step), typically a hidden tab. A device that is slow from the first window never raises it, so it is not the signal for how fast the device is (read it as in [Try it on your phone](/docs/sdk/on-device/#try-it-on-your-phone)).

- `quality.warning`: Engine says the quality of what reaches it is not good enough.

- `stream.unavailable`: the event stream did not connect; the capture goes on.

- `hci.coverage`, `analysis.degraded` and `kpi.aggregate_only`: the analysis is partial or lacks some indicators.

- `target.inferred` and `contract.version`: the context was not set as declared, or Engine speaks another contract version.

- `protocol.not-interpreted` (since 0.29.0): Engine says the protocol is not interpreted (`interpreted: false`, Measurement). The SDK sends no taxonomy and asks for no analysis, even if you passed `triggerAnalysis: true`; `interpretation` will be `null`, as expected. Once per capture, live and recording.

- `analysis.out-of-token-scope` (since 0.29.0): with a capture token, which may not call `/analyze*`. Live, since 0.38.0, the interpretation arrives anyway over the event stream, and this warning appears only if Engine's notice does not arrive in time and the `/analyze` fallback answers `403`; with `interpretation: 'stream'` no interpretation is produced, so use the default with a capture token. In the processing service's replay ([Processing service](/docs/sdk/processing/#the-token-url)), Engine runs the interpretation the closing `Final` asked for. Either way the session ends `complete` with its results.

- `interpretation.sse-timeout` (since 0.38.0): Engine's notice that the interpretation is ready did not arrive in time (`analyzeTimeoutMs`, or 120 s if the stream never connected), and the stored one was read with `POST /analyze`. It names the cause: a stream that never connected, one that dropped during the wait (`SessionReport.streamDropsDuringWait`; check that your proxy forwards `/stream/{userProtocolId}`), or an Engine slower than `analyzeTimeoutMs`.

- `analysis.in-progress` (since 0.44.0): at the close of a capture, `POST /analyze` answered `202 ANALYSIS_IN_PROGRESS`; once per such answer. The SDK waits and asks again by itself: say "interpreting", not "no interpretation". Since 0.45.0, `interpretation.sse-timeout` and `analysis.regenerated` after a `202` count that wait in the time they report

- `analysis.regenerated` (since 0.38.0): `POST /analyze` answered `from_cache: false`, so it generated a new interpretation instead of serving the stored one; the session may have been billed twice.

- `analyze.progress`: deprecated, and since 0.38.0 only with `interpretation: 'stream'` and no `onProgress` on the client. Pass `onProgress({ phase, route })` to receive the phases there.

- `transport.rate-limited` (since 0.37.0): with a capture token, Engine limited this capture's requests (`429` `CAPTURE_TOKEN_RATE_LIMIT`) and the SDK waits the `Retry-After` before sending the same request again; it names the route and the wait. Nothing is lost: the capture goes on, slower. At most 2 minutes at a time and 5 times in a row per request; beyond that, the request fails as before.

- `score-index.malformed` (since 0.39.0): `readScoreIndex()` found the index key in the interpretation's structured data, but with a shape it does not recognise, and returned `null`. It only appears if you pass `onWarning` to `readScoreIndex()`; in `capture-server` it is a message starting `score-index.malformed:`. See [Results](/docs/concepts/results/#a-0-to-100-index).

- Transcription: `stt` (with a `blocker`, the device cannot transcribe; for a `{ type: 'video' }` or `{ type: 'stream' }` source with no audio track, since 0.43.0 the message says so (the capture source has no audio track, so there is nothing to transcribe and this capture goes on without transcription): use a source with sound or set `transcribe: false`; otherwise, it could not start, for example a CSP without `blob:` in `script-src`, and then the report's `transcription` is `null`), `stt.cut` (cut mid-session), `stt.autodetect` (the language was detected, not pinned: the text can come back translated into English), `stt.discarded` (speech of a step that a filter discarded, so it never reached the transcript: low confidence, a repetition loop, the Silero gate or the anti-stuck cut), `stt.speechDiscarded` (a span of continuous noise discarded before the model), `stt.silent` (the microphone worked and nothing was transcribed: read the report's `transcription.discarded*`) and `stt.mainThread` (speech runs on the main thread: every utterance stops the video, expect fewer frames). Since 0.43.0, with `allowWasmWorker` (no WebGPU), a transcription Worker that does not start no longer falls back to the main thread: there is no transcription (`codec.error` with `wasm-needs-worker`, and `SessionReport.transcriptionLoad.reason` is `'needs-worker'`) and the capture goes on without voice. The report's `transcription.lostOnClose` counts the utterances still being transcribed or queued when the capture stopped; since 0.43.0 that includes one cut by an `abort()` or a `stop()` in the middle of a step, where before it could read `0`. See [CSP and transcription](/docs/guides/csp-transcription/).

- Transcription per step, before the camera opens (since 0.38.0): `transcription.off-on-voice-step` (`transcribe` is off and the plan has steps where the person is expected to speak, `expectsSpeech: 'yes'`; it names their types), `transcribeSteps.excludes-voice-step` (`transcribeSteps` leaves out one of those steps) and `transcribeSteps.noMatch` (no type in `transcribeSteps` exists in the plan: no step is transcribed). `transcribeSteps.unknownType` now means only that some of the types do not exist; the steps that match are still transcribed.

- The startup (since 0.42.0): `startup.stalled` (a download of `face-model` or `speech` brings no new byte for `stallMs`, 20 s by default; one per stall, with `stage`, `subStage`, `messageKey` and `userMessage`; it cuts nothing), `stt` with `reason: 'timeout'` (the speech cap ran out: the capture goes on without speech), `prepare.stale` (a capture could not use a prepared part, with `part`, `fields` and `reason`, and loads it itself), `prepare.released` (what `prepare()` loaded was released, with its `reason`, such as `'replaced'`, `'release'`, `'abort'` or `'pagehide'`; since 0.43.0, with `keepPrepared`, also `'unusable'` with its `part`: kodec left a kept part unusable while it waited for the next capture, and only that part is released) and, in record mode, `recording.option-ignored` for `startup.timeouts.vision` and `startup.timeouts.speech` (a recording has neither phase). See [On-device](/docs/sdk/on-device/#the-startup-screen).

- The face (since 0.43.0, for a capture and a baseline): `prepare.face-lost` (the prepared face rejected its first frames or lost its GPU context, and kodec loads it again once; the report keeps the face `'adopted'`, with `faceReloaded: true`) and `face.context-lost` (the same for a face the capture loaded itself, a driver reset or resuming from sleep: no frames while it reloads). Neither is a `codec.error`. A second loss in the same capture, or a reload that fails, stops it with `capture-failed`; on Safari 16.x the loss cannot be watched and stays silent.

- `codec.error`: kodec raised an error, reported once per code and counted in the report's `codecErrors` (`SessionReport`). `no-audio-track` is informational (every live session without transcription has it); `audio-start-failed` loses the transcription. Since 0.43.0 (kodec 5.0.0-rc.14) the face reload of `face.context-lost` and `prepare.face-lost`, and a `capture-stalled` gap that falls within it, are not counted; a gap that starts before the loss or ends after the reload still is, and so is a lost camera (`track-ended`).

- `baseline.framesLost`: only from `captureBaseline()`. The server confirmed fewer frames of a batch than it carried: the rest are not in the baseline and nothing retries them.

- `audience.not-applied`: the audience you asked for was not applied, and the interpretation came in the default reading. It is the only signal: there is no route to list the audiences, so check the label ([Interpretation for an audience](/docs/concepts/results/#interpretation-for-an-audience)).

More in [On-device](/docs/sdk/on-device/#errors-and-warnings).

## Deferred, in the browser

`uploadRecording` rejects with `UploadRecordingError` (`code`, `status`, `retryable`):

| Code | When | Retryable | What to do |
| --- | --- | --- | --- |
| `E_UPLOAD_NETWORK` | Network, 5xx (including 503 `E_BUSY`, with its `Retry-After`), 408, 429 or the 409 of a part, after the retries | Yes | Call again later: the local copy is still there |
| `E_UPLOAD_NOT_NOTIFIED` | Your receiver stored it but its `onComplete` failed | Yes | Tell the user it is uploaded; call again later (your backend can retry `onComplete` itself with `receiver.notify()`) |
| `E_UPLOAD_AUTH` | 401: no session | Yes, after signing in | Sign the user in and call again |
| `E_UPLOAD_REJECTED` | 403, 400, 413, 415 or too many open uploads | No | It is not this user's, or it is malformed |
| `E_UPLOAD_CONFLICT` | A 409 that is not a resync | No | A defect: report it; it is not retried |
| `E_UPLOAD_TOO_LARGE` | Over `maxBytes` | No | Record shorter or at a lower bitrate |
| `E_UPLOAD_LOCAL_UNREADABLE` | The local copy can no longer be read | No | `abandonUpload` |
| `E_UPLOAD_PROTOCOL` | Your receiver answers something impossible | No | Check the receiver |
| `E_UPLOAD_ABORTED` | Your own `signal` | Yes | Call again when you want to resume |

And the recording itself:

| Code | When | What to do |
| --- | --- | --- |
| `E_RECORDER_UNSUPPORTED` | The browser cannot record MP4/H.264 | Another browser (Firefox is not a target: kodec has not been tested there, and it does not record MP4/H.264) |
| `E_RECORDING_LOST` | The camera stops, the recorder fails or the disk is full | Nothing is kept. `abort()` to release the reservation, then record again |
| `E_STORAGE_FULL` | There is no space to keep the recording | Free space and record again |
| `E_CAPTURE_ID_IN_USE` | That `captureId` already has a recording in this browser | Upload or abandon the first one |

More in [Deferred (server-side)](/docs/sdk/deferred/).

## Deferred, in your backend

Your receiver answers with `{ "error": { "code", "message" } }`. These are all the codes of the receiver:

| Code | Status | When |
| --- | --- | --- |
| `E_UNAUTHORIZED` | 401 | No authenticated session |
| `E_FORBIDDEN` | 403 | The subject may not upload a capture for this pair |
| `E_BAD_REQUEST` | 400 | The body is not JSON, or an id or an offset is malformed |
| `E_MANIFEST_INVALID` | 400 | The `size`, the `mimeType` or the manifest do not validate |
| `E_NOT_FOUND` | 404 | No such upload (or it belongs to another subject) |
| `E_METHOD_NOT_ALLOWED` | 405 | A method the route does not accept |
| `E_CAPTURE_ID_CONFLICT` | 409 | That `captureId` belongs to another upload |
| `E_MANIFEST_MISMATCH` | 409 | That `captureId` was started with another size, `mimeType` or manifest |
| `E_ALREADY_COMPLETE` | 409 | The upload is already complete |
| `E_OFFSET_MISMATCH` | 409 | The offset is not where the upload is (the body carries `bytes`); the client resyncs |
| `E_SIZE_MISMATCH` | 409 | `complete` with fewer bytes than the declared `size` |
| `E_UPLOAD_CONFLICT` | 409 | Another chunk of the same capture is in flight |
| `E_UPLOAD_GONE` | 410 | The upload was processed and removed |
| `E_LENGTH_REQUIRED` | 411 | A part without `Content-Length` |
| `E_TOO_LARGE` | 413 | The `size` is over `maxBytes` |
| `E_BODY_TOO_LARGE` | 413 | The body is over the limit |
| `E_PART_TOO_LARGE` | 413 | A part is over `partBytes` |
| `E_UNSUPPORTED_MEDIA_TYPE` | 415 | The `Content-Type` is not the one the route needs |
| `E_TOO_MANY_OPEN` | 429 | The subject has too many unfinished uploads |
| `E_STORAGE` | 500 | The storage cannot answer safely |
| `E_INTERNAL` | 500 | An unexpected failure of the receiver |
| `E_BUSY` | 503 | Another process holds the capture, or its `onComplete` is still running; comes with `Retry-After` |
| `E_NOTIFY_FAILED` | 503 | The upload is stored but your `onComplete` failed or ran too long; comes with `Retry-After: 30` |

On the video route, `E_BAD_SIGNATURE` (403) means a bad or expired video URL.

The proxy answers with the same shape, plus the status and body of Engine as they are:

| Code | Status | When |
| --- | --- | --- |
| `E_ROUTE_NOT_ALLOWED` | 404 | A route that is not in the list of the proxy |
| `E_METHOD_NOT_ALLOWED` | 405 | A method the route does not accept |
| `E_FORBIDDEN` | 403 | Your `authorize` refused, or the origin is not allowed |
| `E_BAD_REQUEST` | 400 | The ids in the path are malformed |
| `E_UNSUPPORTED_MEDIA_TYPE` | 415 | The body is not `application/json` |
| `E_BODY_TOO_LARGE` | 413 | The body is over `maxBodyBytes` of `createEngineProxy` (16 MiB by default from `capture-server` 0.12.0; 8 MiB before). The SDK sees it as `E_UPLOAD_FAILED`, final at the first try |
| `E_ENGINE` | 502 | Engine could not be reached, or no token could be obtained |
| `E_RATE_LIMITED` | 503 | Engine rate-limited the token; try again later |
| `E_INTERNAL` | 500 | An unexpected failure of the proxy |

The processing service's `errorCode`, with whether to retry and whether the reservation is released: [Processing service](/docs/sdk/processing/#error-codes).

## HTTP errors from Engine

Engine answers errors with this shape:

```json
{ "status": 401, "body": { "code": 401, "message": "Invalid credentials." } }
```

`code` is the HTTP status. On a `202`, `403`, `409` or `422` the body can also carry a `reason` to branch on: they are in [Limits](/docs/concepts/limits/#error-reasons).

### The 202 of the interpretation

`client.analyze(userProtocolId, protocolMechanicId)` in the page (`@neurologyca/capture` 0.44.0 or later) and `admin.analyze(pair)` in your backend (`capture-server` 0.20.0 or later) do not throw on a `202`: they return `interpretation: null` with `inProgress: true` and `retryAfterMs` (Engine's `retryAfterSeconds` in ms, in the page else its `Retry-After` header; `null` when it does not say), and Engine's body in `raw` (`reason: 'ANALYSIS_IN_PROGRESS'`, `raw.retryAfterSeconds`). Engine is still interpreting that session, so a `202` counts as "interpreting", never as "no interpretation": wait `retryAfterMs` (about 30 s when it is `null`), ask again a few times at most and, if it is still in progress, show it as interpreting and ask later (or wait for `constellation.complete` on the stream). Only a `null` with `inProgress: false` is final. A `202` does not start another analysis, so asking again is not billed again. At the close of a capture the SDK already does this by itself (`analysis.in-progress`, then `E_ANALYSIS_IN_PROGRESS` if the wait runs out); this helper is for reading it later. Through a proxy on another origin, the page only reads `Retry-After` with `capture-server` 0.20.1 or later ([The proxy](/docs/api/proxy/)).

```js
// A 202 from /analyze means "interpreting", not "no interpretation". client.analyze() in the page (@neurologyca/capture
// 0.44.0 or later) and admin.analyze() in your backend (capture-server 0.20.0 or later) say so: interpretation: null,
// inProgress: true and retryAfterMs, the wait Engine asks for (null when it does not say).
/**
 * @param {() => Promise<{ interpretation: string | null, inProgress: boolean, retryAfterMs: number | null, raw: unknown }>} ask
 *   in the page: () => client.analyze(userProtocolId, protocolMechanicId); in your backend: () => admin.analyze(pair)
 * @param {{ tries?: number, wait?: (ms: number) => Promise<void> }} [o]
 * @returns {Promise<{ interpretation: string | null, interpreting: boolean, raw: unknown }>}
 */
export async function askInterpretation(ask, { tries = 4, wait = (ms) => new Promise((r) => setTimeout(r, ms)) } = {}) {
  for (let i = 1; ; i++) {
    const { interpretation, inProgress, retryAfterMs, raw } = await ask()
    if (!inProgress) return { interpretation, interpreting: false, raw }
    if (i >= tries) return { interpretation: null, interpreting: true, raw } // still interpreting: show it so, ask later
    await wait(retryAfterMs ?? 30_000) // Engine's wait, else about 30 s
  }
}
```

## What the SDK retries on its own

Batches: 3 tries within 30 s. Uploads: 6 tries, respecting `Retry-After`; a `504` on `complete` is retried like a `503`. The token: one more mint after a `401`. Nothing else: the rest is yours.

## Support

Write to the contact in your invitation (it is not in these docs). Send the `X-Correlation-Id` the SDK sent: Engine does not return it today, so take it from your side. The SDK sends it on the interpretation calls, with the `correlationId` of your config or, without one, an id it generates, and `session.correlationId` holds it. Also send the `captureId`, the SDK version you run (`version` in `@neurologyca/capture`'s `package.json`), the time with its time zone, and the environment (test or production). Never send keys, tokens or the person's data.
