Manejo de errores

El SDK proporciona una jerarquía de errores estructurada para un manejo preciso de errores en autenticación, red, operaciones de huellas y configuración.

Jerarquía de errores

Todos los errores del SDK extienden SDKError, que a su vez extiende el Error nativo. Las subclases especializadas — AuthError, NetworkError, FingerprintError, ConfigError y ParseError — permiten comprobaciones precisas con instanceof.

SDKErrorMeta

Cada error del SDK incluye un objeto meta opcional con información contextual:

interface SDKErrorMeta {
  httpStatus?: number;              // Código de estado HTTP (si aplica)
  cause?: unknown;                  // Error original o descripcion de la API
  details?: Record<string, unknown>; // Informacion adicional (apiErrorCode, apiErrorUser, date)
}

Códigos de error

Código	Clase	Cuando se lanza
CONFIG_ERROR	ConfigError	Falta apiBase, HHID inválido, fallo al recopilar encabezados en tiempo de ejecución
NETWORK_ERROR	NetworkError	Fallo de fetch, driver no inicializado, tiempo de espera de comando agotado
AUTH_ERROR	AuthError	Fallo de login, respuestas 401/403, fallo al cerrar sesión
FINGERPRINT_ERROR	FingerprintError	Fallo de operación (identificar, verificar, crear, eliminar, imagen)
PARSE_ERROR	ParseError	Respuesta JSON inválida, respuesta de token inválida
UNKNOWN_ERROR	SDKError	Errores de API no reconocidos, fallos de almacenamiento

Manejo de errores

Captura SDKError como clase base — todos los errores del SDK exponen code y 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);
  }
}

Desde meta puedes extraer el estado HTTP y detalles de la API cuando estén disponibles:

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 con subclases

También puedes usar instanceof con subclases específicas como AuthError, NetworkError, FingerprintError, ConfigError o ParseError cuando necesites restringir el tipo.

Mapeo de errores de API

Las respuestas de la API se mapean automáticamente a tipos de error del SDK mediante mapApiErrorToSDKError:

Estado HTTP	Error mapeado
401	AuthError
403	AuthError
Otro	FingerprintError

El mapeador extrae errorCode, errorDes, errorUser y date del cuerpo de la respuesta de la API y los almacena en SDKErrorMeta.details.

Envuelve siempre las llamadas al SDK

Usa siempre try/catch alrededor de las operaciones del SDK. Los errores no manejados pueden dejar al cliente en un estado inconsistente.