Skip to content
DevLab

Errors, warnings and retries

Every error and warning of the SDK, by layer and by mode, what the SDK retries on its own, and what to send to support.

On this page
  1. The rule that cost an incident
  2. Three families
  3. On-device
  4. Usage errors
  5. Warnings worth showing
  6. Deferred, in the browser
  7. Deferred, in your backend
  8. HTTP errors from Engine
  9. The 202 of the interpretation
  10. What the SDK retries on its own
  11. Support

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.

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.

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; 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); 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.

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

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.

  • 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).

  • 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), 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.

  • 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.

  • 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.

  • 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).

More in On-device.

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).

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.

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.

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).

JavaScript
// 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
}
}

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.

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.