Declared limits and failure modes
What Engine does not do, the technical limits, the mistakes that still answer 2xx, and the error bodies.
What Engine does not do
Section titled “What Engine does not do”- 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.
When the interpretation does not know
Section titled “When the interpretation does not know”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.
Technical limits
Section titled “Technical limits”- 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.readyis sent once per position, when its capture is complete, and not in every case: keep polling/resultsas 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.
| What | Limit | What happens |
|---|---|---|
POST /token through the SDK proxy | 10 per minute per IP, declared by Engine; cache the token | If Engine does answer 429, the proxy answers 503 E_RATE_LIMITED with Retry-After. |
| Request body through the proxy | 16 MiB | The 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 request | 120 s | Event streams are not cut by it. |
| Open uploads per person | 3 | One more answers E_TOO_MANY_OPEN. |
| Upload sizes | Start 1 MiB, chunks of 2 MiB, video up to 1 GiB | Your receiver can lower the video limit (maxBytes). |
| Processing queue | 50 jobs | With more waiting, the service answers E_QUEUE_FULL; jobs run one at a time. |
| Signature window (token URL and webhook) | ±300 s | A server clock off by more is refused as a bad signature. |
| Nonces kept | 600 s | A repeated nonce inside the window is refused as a replay. |
| Webhook body | 1 MiB | No results webhooks in the SDK flow: this is the processing service's webhook to your backend. |
| Step durations | stepDurations: warn (default), enforce or off | Engine does not enforce step durations; the SDK warns by default and, with enforce, refuses with E_STEP_DURATION. |
Mistakes that still answer 2xx
Section titled “Mistakes that still answer 2xx”| 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 |
Errors
Section titled “Errors”| 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": "…" } |
{ "status": 400, "empty": false }{ "status": 404, "body": { "code": 404, "message": "Not found." } }Error reasons
Section titled “Error reasons”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 |
Quality codes
Section titled “Quality codes”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 |