Error Codes
HTTP Status Codes
| Code | Meaning |
|---|---|
200 | Success |
400 | Bad Request: missing required field or malformed JSON |
401 | Unauthorized: invalid or missing API key / token |
403 | Forbidden: valid key but insufficient permissions |
404 | Not Found: customer, session, or resource not found |
429 | Too Many Requests: rate limit exceeded |
500 | Internal Server Error |
Session Status Types
FaceGuard sessions have an internally-tagged status:
| Status Type | Fields | Description |
|---|---|---|
in_progress | stages | Session is active, user is in the verification flow |
completed | outcome, stages, completed_at | Session finished |
bypassed | expires_at, completed_at | Customer has an admin-granted bypass |
Completed Outcomes
| Outcome | Description |
|---|---|
passed | Face matched the base photo |
failed | Face did not match |
PostMessage Close Reasons
Events emitted from FaceGuard to the host application:
| Reason | Payload | Description |
|---|---|---|
approved | { confidence: number } | Face verified successfully |
rejected | { confidence: number } | Face did not match |
canceled | User tapped X to close | |
bypass_active | { bypass_expires_at: string } | Customer has an active bypass |
no_base_photo | No enrolled photo to compare against | |
error | { error: string } | Camera issue, network error, expired token, etc. The error value is a typed code — see below. |
Camera Error Codes
When the user's camera cannot be started, FaceGuard emits { action: 'close', reason: 'error', error: <code> } with one of the codes below. You can switch on the code to render product-specific recovery UI.
| Code | Underlying cause | Suggested guidance |
|---|---|---|
camera_permission_denied | User (or browser/OS policy) denied camera access (NotAllowedError) | Ask the user to enable camera access in browser site settings (web) or device Settings → your app (mobile WebView) |
camera_unavailable | No camera device present (NotFoundError) | Suggest using a device with a camera |
camera_in_use | Another app or tab is holding the camera (NotReadableError, TrackStartError) | Ask the user to close other apps or tabs using the camera |
camera_constraints | Requested resolution / facing mode unsupported (OverconstrainedError) | Rare — usually indicates a hardware limitation |
camera_insecure_context | Page not served over HTTPS, or iframe missing allow="camera" (SecurityError) | Verify the integration host serves HTTPS and the iframe has allow="camera" |
camera_unknown | Catch-all for unexpected getUserMedia failures | Generic retry / contact support |
SDK Result Statuses
When using FaceGuard.verify():
| Status | Confidence | Error | Description |
|---|---|---|---|
approved | 0-100 | Face verified | |
rejected | 0-100 | Face did not match | |
canceled | - | User closed | |
error | string | Something went wrong. error is one of the camera codes above, 'no_base_photo', or another error string. |
Confidence Score
The confidence score (0-100) represents the similarity between the captured face and the enrolled base photo. Higher scores indicate a stronger match.