Skip to main content
This section outlines SDK response codes, structured error handling patterns, session validation checks, SDK lifecycle controls, and capability retrieval. It ensures proper handling of API responses, session states, and operational failures during integration.
Error KeyUser-facing MessageWhen TriggeredError Code
CRYPTOGRAPHIC_ERRORA security issue occurred. Please try again.RSA handshake or payload encryption/decryption failed.400
SESSION_ERRORWe couldn’t load your session. Please try again.Session ID or token is missing, expired, or invalid.400
INVALID_REQUESTSomething’s wrong with the request. Please try again.The API received a malformed or incomplete request payload.400
INVALID_CONFIGURATIONSystem setup error. Please try again.Channel configuration is missing or misconfigured on the backend.400
TIMEOUTRequest timed out. Please try again.The backend did not respond within the expected time window.408
DB_ERRORSomething went wrong. Please try again.A database-level error occurred on the backend.500
ENGINE_ERRORSystem error. Please try again.The biometric or document processing engine encountered an error.500
INTERNAL_ERRORAn unexpected error occurred.An unhandled exception on the backend or in the SDK pipeline.500
INVALID_OPERATIONPlease scan again.Operation not permitted in the current state (e.g. invalid QR re-scan).400
INVALID_DATAPlease check your input and try again.Provided data failed validation — document number format, image quality, etc.400
SDK_INTERNAL_ERRORSDK Internal Error.init() was not called or failed before a data method was invoked.400
UNAUTHORIZED_ACCESSUnauthorized access. Please login again.Authentication failed due to invalid credentials, expired token, or missing authorization header.401
JOURNEY_ERRORUnable to complete the verification journey. Please try again.The verification journey failed due to an invalid state transition or backend journey processing issue.400

​
2. Error Handling

Errors should be accessed from the errors array when code !== 200. 
const res = await Quepass.someMethod(...);

if (res.code === 200) {
  // Safely use res.data
} else {
  const message = res.errors?.[0]?.message ?? 'Unknown error';
  navigate('/error', { state: res });
}
If a backend Message key matches a known SDK error, it is mapped to a human-readable message before being returned in errors[0].message. If the message key is not recognised, the SDK falls back to:
  1. The backend Details field
  2. A generic fallback message

​
3. Session Handling

Use Quepass.isSessionTimedOut() to check whether the current session has expired. If the session is timed out, re-initialize the SDK before making additional requests. 
if (Quepass.isSessionTimedOut()) {
   // Re-initialize SDK
}

​
4. Close SDK

Call Quepass.closeSDKProcess() to properly terminate the SDK process when required. 
Quepass.closeSDKProcess();

​
5. SDK Capabilities

Use Quepass.getSdkCapabilities() to retrieve SDK metadata such as version details. 
Quepass.getSdkCapabilities((success, data) => {
  if (success && data) {
     const version = data.version;
  }
});
If the backend returns a Message key not in ERROR_CODES, the SDK falls back to the Details field of the response, then to a generic fallback string.