Error Handling

The SDK provides a structured error hierarchy for precise error handling across authentication, network, fingerprint operations, and configuration.

Error hierarchy

All SDK errors extend SDKError, which itself extends the native Error. Specialized subclasses — AuthError, NetworkError, FingerprintError, ConfigError, and ParseError — allow precise instanceof checks.

SDKErrorMeta

Every SDK error includes an optional meta object with contextual information:

interface SDKErrorMeta {
  httpStatus?: number;              // HTTP status code (if applicable)
  cause?: unknown;                  // Original error or API description
  details?: Record<string, unknown>; // Additional info (apiErrorCode, apiErrorUser, date)
}

Error codes

Code	Class	When thrown
CONFIG_ERROR	ConfigError	Missing apiBase, invalid HHID, runtime header collection failure
NETWORK_ERROR	NetworkError	Fetch failure, driver not initialized, command timeout
AUTH_ERROR	AuthError	Login failure, 401/403 responses, session close failure
FINGERPRINT_ERROR	FingerprintError	Operation failure (identify, check, create, delete, image)
PARSE_ERROR	ParseError	Invalid JSON response, invalid token response
UNKNOWN_ERROR	SDKError	Unrecognized API errors, storage failures

Handling errors

Catch SDKError as the base class — every SDK error exposes code and meta:

import { Errors } from '@heuristik/hhjssdk';

try {
  await client.init();
  const result = await client.operations.identifyPerson(1);
} catch (err) {
  if (err instanceof Errors.SDKError) {
    console.error(`ERROR (${err.code}): ${err.message}`);
    console.debug('SDKError:', { code: err.code, meta: err.meta });
  } else if (err instanceof Error) {
    console.error('Unexpected error:', err.message);
  } else {
    console.error('Unknown error:', err);
  }
}

From meta you can extract HTTP status and API details when available:

if (err instanceof Errors.SDKError) {
  console.error('HTTP status:', err.meta?.httpStatus);
  console.error('API error code:', err.meta?.details?.apiErrorCode);
  console.error('User message:', err.meta?.details?.apiErrorUser);
}

instanceof with subclasses

You can also use instanceof with specific subclasses like AuthError, NetworkError, FingerprintError, ConfigError, or ParseError when you need to narrow the type.

API error mapping

API responses are automatically mapped to SDK error types by mapApiErrorToSDKError:

HTTP Status	Mapped Error
401	AuthError
403	AuthError
Other	FingerprintError

The mapper extracts errorCode, errorDes, errorUser, and date from the API response body and populates SDKErrorMeta.details.

Always wrap SDK calls

Always use try/catch around SDK operations. Unhandled errors may leave the client in an inconsistent state.