# Declared limits and failure modes

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

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

- 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](/docs/sdk/steps/#checking-the-durations)).
- 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](/docs/concepts/capture/)) and on the device ([Devices, quality and mode](/docs/start/devices-and-modes/)).

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

| 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

| 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](/docs/concepts/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." } }
```

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

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 |
