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.
Specific Error Codes
The API defines a set of error codes to distinguish between various failure modes:
| Error Code | Name | Description |
|---|---|---|
| 1 | SPOOF | Spoofing Attempt Detected — Static image, deepfake, or synthetic biometric detected. |
| -5 | DESKTOP | Desktop Mode Restricted — Attempted operation in disallowed desktop environment. |
| -7 | CAMERA_FAIL | Camera Failure — Could not initialize or capture from camera. |
| -10 | LOW_LIGHT | Low Ambient Light — Insufficient lighting for reliable biometric capture. |
| -11 | MULTIPLE_FACES | Multiple Faces Detected — Ambiguity during biometric analysis. |
| -13 | — | Session Expired — Session no longer valid. |
| -14 | — | Unauthorized Callback — Callback attempted without valid credentials. |
| -15 | — | Token Already Used — Possible replay attack detected. |
| -16 | — | Device Mismatch — Device differs from registration source. |
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.