Behavioral Biometrics (BehavioIQ)
Common objects & errors
All four Behavioral endpoints fail the same way — one envelope, one set of codes, defined once here and referred to by name from each endpoint page.
Error Responses
All endpoints return errors in the following format:
{
"errors": [
{
"message": "description of the error",
"code": "error_code"
}
]
}
errors[].codeis the semantic server error code. On the SDK-authenticated endpoints, the Behavioral SDKs surface this value directly on the error they raise so client code can branch on it: AndroidTSSessionError.NetworkError.serverErrorCode, iOSApiError.serverErrorCode, and FlutterPlatformException.details['serverCode'].
Common Error Codes
| HTTP Status | Code | Description |
|---|---|---|
| 400 | invalid_param | Missing or invalid request parameter |
| 400 | invalid_challenge_id | Challenge ID is not a valid UUID |
| 400 | challenge_not_found | Challenge does not exist |
| 400 | challenge_access_denied | Challenge does not belong to this client |
| 400 | invalid_challenge_status | Challenge has already been submitted or is invalid |
| 400 | customer_user_device_not_found | The challenge's device record does not exist |
| 400 | customer_user_device_deactivated | The challenge's device has been deactivated |
| 400 | no_batch_events | No batch events found for this challenge |
| 400 | invalid_batch_events | Batch events failed hash chain or sequence validation |
| 400 | missing_nonce | Nonce is missing from request |
| 400 | invalid_nonce | Nonce does not match the challenge or is expired |
| 400 | missing_challenge_id | Challenge ID is missing from context |
| 403 | access_denied | Invalid credentials, signature, or deactivated key |
| 403 | request_time_too_skewed | Timestamp too far from server time |
| 500 | internal_server_error | Internal server error |
| 503 | bootstrap_failed | First-session enrollment failed (scoring engine unavailable / timed out). Retry |
| 503 | bootstrap_wait_timeout | Another request is enrolling this user's baseline and did not finish in time. Retry |
Compute a behavior score additionally returns engine-defined codes with HTTP 200 and data.status: "failure".