ERROR HANDLING
Robust error handling is critical for a secure and reliable biometric authentication system. The PrivateID Session API returns detailed error information through standardized error codes and HTTP status responses. These mechanisms facilitate precise debugging, support automated retry strategies, and ensure that critical security events are promptly flagged.
Error Codes
The API defines a set of error codes to distinguish between various failure modes. Each code is classified as either Fatal (ends the session and triggers the webhook) or Diagnostic (accumulated in the errorCodes array for observability without ending the session).
| Error Code | Name | Type | Description |
|---|---|---|---|
| 1 | SPOOF | Fatal | Spoofing Attempt Detected — Static image, deepfake, or synthetic biometric detected. |
| -5 | DESKTOP | Fatal | Desktop Mode Restricted — Attempted operation in disallowed desktop environment. |
| -7 | CAMERA_FAIL | Fatal | Camera Failure — Could not initialize or capture from camera. |
| -8 | SESSION_EXPIRED | Fatal | Session Expired — Verification session has exceeded its configured time-to-live (TTL) and is no longer valid. |
| -9 | FACE_NOT_MATCH | Fatal | Face Not Matching — The captured face does not match the biometric data associated with the provided customerId. |
| -10 | LOW_LIGHT | Fatal | Low Ambient Light — Insufficient lighting for reliable biometric capture. |
| -11 | MULTIPLE_FACES | Fatal | Multiple Faces Detected — Ambiguity during biometric analysis. |
| -14 | — | Fatal | Unauthorized Callback — Callback attempted without valid credentials. |
| -15 | — | Fatal | Token Already Used — Possible replay attack detected. |
| -16 | — | Fatal | Device Mismatch — Device differs from registration source. |
| -20 | MODEL_LOAD_FAILED | Diagnostic | Face/document scanning models failed to load. |
| -22 | FACE_SCAN_ERROR | Diagnostic | Face scanning SDK encountered an error. |
| -23 | DOCUMENT_SCAN_ERROR | Diagnostic | Document scan failed due to corrupted embeddings. |
| -24 | SESSION_LOAD_FAILED | Diagnostic | Client failed to fetch session from API. |
Diagnostic codes are deduplicated per session — each code is sent to the backend at most once. These codes are encrypted before transmission and do not interrupt the user flow; they are reported for backend observability only.
General HTTP Status Errors
Standard HTTP status codes also indicate common failure modes:
| HTTP Status Code | Meaning | Possible Causes |
|---|---|---|
| 401 | Unauthorized | Missing or invalid x_api_key, clientID, clientSecret, or SLC. |
| 400 | Bad Request | Malformed JSON, missing parameters, or invalid field types. |
| 500 | Internal Server Error | Transient server-side issue or cryptographic operation failure. |
Error Response Format
When an error occurs, the API returns a structured JSON payload:
{
"status": "error",
"message": "Camera failure detected",
"errorCodes": [-7]
}
Fields:
status: Always set to"error"on failure.message: Human-readable message.errorCodes: Array of numeric codes.
Cryptographic and Audit Considerations
Immutable Audit Trails: All error events are logged with cryptographically signed audit trails. This ensures that the logs are tamper-evident and can be reliably used for forensic analysis without compromising sensitive biometric data.
Error Isolation and Granularity: The defined error codes are granular enough to distinguish between security-critical issues (e.g., spoofing attempts) and operational issues (e.g., low-light conditions), enabling tailored remediation strategies.
Automated Remediation: The detailed error responses allow clients to implement automated error-handling routines.
Data Integrity: Errors occurring during cryptographic token generation or comparison trigger immediate alerts, ensuring that any discrepancies are promptly addressed. This minimizes the risk of compromised authentication integrity.
Implementation Recommendations
Logging and Monitoring: Integrate robust logging mechanisms that capture both the error response and associated audit metadata. Ensure that these logs are stored securely and are accessible for forensic analysis.
Automated Alerts: Configure monitoring systems to trigger alerts on detection of critical errors (e.g., SPOOF attempts or repeated CAMERA_FAIL events) to enable immediate investigation and remediation.
Client-Side Handling: Implement client-side error handling that differentiates between permanent errors (e.g., invalid credentials) and transient errors (e.g., low ambient light) to optimize the user experience and system throughput.