Skip to content
DevLab

Declared limits and failure modes

What Engine does not do, the technical limits, the mistakes that still answer 2xx, and the error bodies.

On this page
  1. What Engine does not do
  2. When the interpretation does not know
  3. Technical limits
  4. Limits of the SDK and of the deferred mode
  5. Mistakes that still answer 2xx
  6. Errors
  7. Error reasons
  8. Quality codes
  • It does not infer intent, detect deception or diagnose. Wellness readings are pre-diagnostic.
  • Indicators describe the interaction, not the person: “this interview produced rejection at minute twenty”, never “this candidate is a person who rejects”.
  • Arousal is expressive intensity, not physiological activation.

The whitepaper declares how the interpretation behaves at its limits: “uncatalogued” when no case fits, a lower reliability for low-quality signal, population calibration only when there is no personal baseline, and no citations when there is no corpus. The HTTP results do not expose reliability or calibration fields yet.

  • One completed capture per position and enrolment: to measure again, enrol again.
  • Step durations are guidance: Engine does not enforce them, but the SDK warns by default and can refuse (stepDurations, Steps and marking).
  • The first seconds of a capture have no value for the indicators computed over a window of frames, such as workload.
  • A session with no batch for a while is abandoned; the threshold is a setting of the environment.
  • results.ready is sent once per position, when its capture is complete, and not in every case: keep polling /results as a fallback.
  • Measurement captures are not interpreted.
  • What you get also depends on the person’s conditions (Capturing for the best accuracy) and on the device (Devices, quality and mode).

Limits of the SDK and of the deferred mode

Section titled “Limits of the SDK and of the deferred mode”

What the SDK and your backend add on top of Engine’s limits. There are no results webhooks in the SDK flow: the only webhook is the processing service’s, in deferred.

Limits of the SDK and of the deferred mode
WhatLimitWhat happens
POST /token through the SDK proxy10 per minute per IP, declared by Engine; cache the tokenIf Engine does answer 429, the proxy answers 503 E_RATE_LIMITED with Retry-After.
Request body through the proxy16 MiBThe createEngineProxy default (maxBodyBytes) from capture-server 0.12.0; 8 MiB before. From SDK 0.34.0 a live batch carries at most 3 MB of frames; an SDK before 0.34.0 sends up to about 9.3 MB with a camera, so in front of it allow at least 10 MB. DevLab's own gateway allows 10 MiB. A larger body gets 413 E_BODY_TOO_LARGE before it reaches Engine.
Proxy timeout per request120 sEvent streams are not cut by it.
Open uploads per person3One more answers E_TOO_MANY_OPEN.
Upload sizesStart 1 MiB, chunks of 2 MiB, video up to 1 GiBYour receiver can lower the video limit (maxBytes).
Processing queue50 jobsWith more waiting, the service answers E_QUEUE_FULL; jobs run one at a time.
Signature window (token URL and webhook)±300 sA server clock off by more is refused as a bad signature.
Nonces kept600 sA repeated nonce inside the window is refused as a replay.
Webhook body1 MiBNo results webhooks in the SDK flow: this is the processing service's webhook to your backend.
Step durationsstepDurations: warn (default), enforce or offEngine does not enforce step durations; the SDK warns by default and, with enforce, refuses with E_STEP_DURATION.
You did Engine answers What happens
Omitted triggerAnalysis on the last batch 202 No interpretation is requested. With the SDK it is the other way round
Sent frames without featuresMeta 202, framesWithoutFeaturesMeta above 0 No valence or arousal axes for those frames
Sent frames with a different number of landmarks or coefficients 202 Landmarks: 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. Coefficients: the frame is used without them
Skipped the Final of a step 202 The step never closes; the session is abandoned
Left a gap in kpnfile.order 202 until the Final The Final answers 400 with KPN-EMO-MISSING-PACKETS and missingOrders (see Quality codes below)
Asked for results too early 200 with empty rawResults and aggResults Poll until the capture completes
Misspelled a field 202 The field is ignored
Resent a batch with different content 202 Engine keeps the first copy
Sent the last baseline batch over a gap 202 with missingOrders No baseline is computed
Enrolled a user without a baseline 201 with baselineWarning Only population calibration applies
Called /analyze again 200, from_cache: true You get the stored interpretation if its analysis came out complete; with metadata.status degraded or failed, Engine regenerates it (from_cache: false), which costs language-model tokens
Cancelled when no capture was open 200, cancelled: false Nothing to cancel
Status When Body
400 Malformed JSON, or a field with the wrong type A JSON body with code and message (for example Field 'x' has an invalid value or type.). Nothing was processed
400 A batch breaks the contract { "code": 400, "message": "…", "qualityCode": "KPN-EMO-STEP" }
400 POST /user-protocols cannot tell which of your contexts the enrolment is for reason: CONTEXT_REQUIRED or CONTEXT_NOT_VALID (below)
401 Missing or expired token Empty, with WWW-Authenticate: Bearer
403 A blocked user { "code": 403, "reason": "USER_BLOCKED", "message": "…" }
404 An id that does not exist or is not yours { "code": 404, "message": "Not found." }
409 Session or position rules reason: see Sessions
409 /analyze on a protocol that is not interpreted, such as Measurement { "code": 409, "reason": "PROTOCOL_NOT_ANALYSED", "message": "…", "hint": "…" }
JSON
{ "status": 400, "empty": false }
JSON
{ "status": 404, "body": { "code": 404, "message": "Not found." } }

When a 202, 400, 403, 409 or 422 carries reason, branch on it; message and hint are for people.

reason Status What happened What to do
USER_BLOCKED 403 The user is blocked Nothing on activity routes until POST /users/unblock
ANALYSIS_IN_PROGRESS 202 POST /analyze while Engine is already analysing that session (not for a single step; the mark expires after 10 min) Not an error: wait for constellation.complete, or call again after retryAfterSeconds (also in Retry-After)
PROTOCOL_NOT_ANALYSED 409 /analyze on a protocol that is not interpreted, such as Measurement Do not call /analyze for it: read the indicators with GET /results
MUST_START_AT_FIRST_POSITION 409 A protocol with a schedule starts at its first position Start with the position in goTo
MECHANIC_NOT_YET_AVAILABLE 409 The position is not open yet Retry at earliestAt; ahead of time, window.earliestAt in nextSessions (test environment’s Engine)
MECHANIC_EXPIRED 409 Its window closed for good Continue with goTo
POSITION_ALREADY_COMPLETED 409 It already has a completed session Do not recapture; enrol again to measure again
SESSION_ABANDONED 409 The capture was abandoned Restart from step 1 with kpnfile.order 1
PROTOCOL_DEPRECATED 409 The protocol was retired. A capture already in progress may finish Enrol in the one in publishedProtocolPid (null if there is none). On a batch it is always null: look the replacement up in GET /catalog/protocols
MECHANIC_DEPRECATED 409 That mechanic was retired What was measured stays; it accepts no new captures
USER_PROTOCOL_RETIRED 409 The enrolment was retired for this user Its results and POST /analyze stay available
CONTEXT_NOT_ASSIGNED 409 The protocol is no longer available to your organization Its results and POST /analyze stay available
CONTEXT_REQUIRED 400 POST /user-protocols for a protocol that belongs to more than one of your contexts, without contextPid Repeat it with contextPid: the pid in GET /catalog/contexts of the context this enrolment is for. Today only through the HTTP API: the SDK does not send contextPid
CONTEXT_NOT_VALID 400 POST /user-protocols with a contextPid that is not one of your contexts that includes this protocol Take it from pid in GET /catalog/contexts, or leave it out if the protocol is in only one of your contexts
POSITION_RESERVED 409 Another attempt holds the position: a capture in progress or a recording waiting to be sent (holder says which) Ask the person; only if they confirm, repeat POST …/context with discardPending: true
CAPTURE_DISCARDED 409 That recording (captureId) was discarded Do not retry
CAPTURE_OUT_OF_ORDER 409 A recording sent later is older than the person’s latest analysed session in the same context Do not retry: the answer will not change
CAPTURE_CANCELLED 409 The end notice of a recording (recordingEndedAt without capturedAt) arrived after it was cancelled or rejected as out of order; nothing is reserved Do not retry
CAPTURE_TOKEN_SCOPE 403 A capture token (POST /token/capture) used outside its capture: another route, mechanic or captureId Use your regular token there; for another capture, request a new capture token
CAPTURE_TOKEN_RATE_LIMIT 429 Only with a capture token: more requests in a minute for that capture than its limit (15 for GET …/schema and POST …/context together, 30 for POST /process-kpn-emo, 60 for the rest). Nothing was processed Wait the seconds in Retry-After and repeat the same request. A new token for the same captureId keeps the count
CAPTURE_ID_IN_USE 409 POST …/recordings with a captureId that belongs to another recording Use a new captureId
ALREADY_UPLOADED 409 POST …/recordings for a recording already uploaded Nothing to do: it is uploaded
UPLOAD_NOT_FOUND 409 POST …/recordings/{captureId}/complete before the video is in storage Finish the PUT to uploadUrl and call again
NOT_UPLOADED 409 GET …/recordings/{captureId}/video before the recording is uploaded Call complete first, then ask for the video URL
SIZE_MISMATCH 409 The uploaded video does not have the announced size (expectedBytes, actualBytes) Upload it again with the announced size, or announce it with a new captureId
STORAGE_UNAVAILABLE 503 The video storage is not available; nothing was changed Retry in a moment
TAXONOMY_INVALID 422 POST …/context with taxonomy ids that do not check out. Not returned today: the same case answers 201 with taxonomyWarnings, whose code is, for example, UNKNOWN_CONTEXT (the issues of the 422 use the same kind of codes, such as SUBCONTEXT_NOT_IN_CONTEXT); the value was stored anyway Fix the ids; code for the 422 now

A 400 from a batch can carry qualityCode: KPN-EMO-STEP, KPN-EMO-MISSING-PACKETS and KPN-EMO-MEDIA on POST /process-kpn-emo; a microintervention batch (POST /interruptions/{interruptionId}/process-kpn-emo) can return any of these except KPN-EMO-MEDIA.

qualityCode Meaning Retry?
KPN-EMO-STEP That step is not in the mechanic’s plan Fix the step
KPN-EMO-MISSING-PACKETS The Final batch arrived but earlier batches of its step did not; missingOrders lists them, and that Final stored nothing Yes: send the batches in missingOrders, then the Final again
KPN-EMO-STEP-TYPE A free-flow mechanic with no default step type No
KPN-EMO-NO-PLAN A fixed-flow mechanic with no steps defined No
KPN-EMO-MECHANIC The offered mechanic does not exist No
KPN-EMO-MEDIA mediaId is not a uuid, is a numeric catalogue id, does not exist, or belongs to another organization’s content (the same answer, before anything is stored) Fix mediaId: use steps[].media[].pid from the script
KPN-EMO-INTERRUPTION-CLOSED The interruption is declined, completed or expired No