Error Handling

@alviere/core provides a typed error code system to help you distinguish recoverable API errors from failures that require immediate user action or a re-authentication flow.

import {
  AlcoreErrorCodes,
  getErrorMessage,
  isCriticalError,
  AlcoreApiError,
} from '@alviere/core';

AlcoreApiError

Service calls throw an AlcoreApiError when the Alcore middleware or the Hive API returns an error. Catch it to access the structured error code.

import { AlcoreApiError, AlcoreErrorCodes, isCriticalError } from '@alviere/core';

try {
  const account = await accounts.getAccount(accountUuid);
} catch (err) {
  if (err instanceof AlcoreApiError) {
    const code = err.code; // e.g. '100306'

    if (isCriticalError(code)) {
      // Force re-authentication or show a blocking error
    } else {
      // Show a recoverable error message to the user
      const message = getErrorMessage(code);
      showError(message);
    }
  }
}

AlcoreErrorCodes

A named constant map of every known error code. Use these instead of hardcoding string literals.

Authentication and session

Name	Code	Description
`ALVIERE_CORE_NOT_INITIALIZED`	`000000`	`AlviereCore` was used before being configured
`INVALID_JWT`	`100305`	The JWT is missing, malformed, or expired
`AUTH_FAILED`	`100306`	Authentication rejected by Alcore
`SESSION_NOT_FOUND`	`110000`	Session does not exist or has expired

Encryption

Name	Code	Description
`UNPROCESSABLE_ENCRYPTED_DATA`	`100011`	Alcore cannot process the encrypted payload
`WRONG_ENCRYPTED_ENDPOINT`	`100012`	Encrypted request sent to a non-encrypted endpoint
`UNDECRYPTABLE_DATA_AT_ENDPOINT`	`100013`	Response data cannot be decrypted
`DECRYPTED_DATA_UNUSABLE_AT_ENDPOINT`	`100014`	Decrypted response is malformed
`WRONG_DECRYPTED_ENDPOINT`	`100015`	Decrypted request reached the wrong endpoint
`WRONG_VERSION_OR_ENDPOINT`	`100016`	Version or endpoint mismatch
`OPERATION_HALTED`	`100017`	Request halted by Alcore security policy

Request validation

Name	Code	Description
`INVALID_REQUEST_PAYLOAD`	`100300`	Request body is invalid
`INVALID_REQUEST_PAYLOAD_FIELD`	`100301`	One or more fields are invalid
`INVALID_PATH_PARAMETER`	`100302`	A path parameter (e.g. UUID) is invalid
`INVALID_HEADER`	`100303`	A required header is missing or malformed
`INVALID_QUERY_PARAMETER`	`100304`	A query parameter is invalid

Resource errors

Name	Code	Description
`NOT_FOUND`	`110002`	The requested resource does not exist
`PARENT_ACCOUNT_NOT_FOUND`	`110001`	Parent account UUID not found
`ACCOUNT_TYPE_NOT_SUPPORTED`	`110004`	Account type is not permitted
`UNDERLYING_API_ERROR`	`115000`	The Hive API returned an upstream error
`ACCOUNT_STATUS_NOT_ACTIVE`	`115001`	Operation requires an active account
`ACCOUNT_CHILD_FORBIDDEN`	`320129`	Child account action is not permitted
`PARENT_ACCOUNT_NOT_ALLOWED`	`320104`	Parent account cannot perform this action
`BANK_ACCOUNT_PRIMARY_REQUIRES_ACTIVE_STATUS`	`340028`	Primary bank account must be in active status
`BANK_ACCOUNT_ALREADY_EXISTS`	`340029`	Bank account is already linked

isCriticalError

isCriticalError(errorCode: string): boolean

Returns true for errors that cannot be retried without user intervention — typically expired sessions, authentication failures, or encryption mismatches.

Critical error codes:

ALVIERE_CORE_NOT_INITIALIZED
INVALID_JWT
AUTH_FAILED
SESSION_NOT_FOUND
UNPROCESSABLE_ENCRYPTED_DATA
WRONG_ENCRYPTED_ENDPOINT
UNDECRYPTABLE_DATA_AT_ENDPOINT
OPERATION_HALTED
UNDERLYING_API_ERROR
ACCOUNT_STATUS_NOT_ACTIVE
ACCOUNT_CHILD_FORBIDDEN
PARENT_ACCOUNT_NOT_ALLOWED

For critical errors, redirect the user to re-authenticate or display a non-dismissable error state. Non-critical errors (validation, not-found, duplicate) can usually be surfaced as inline messages.

getErrorMessage

getErrorMessage(errorCode: string): string

Returns a human-readable message for a given error code. Falls back to a generic message for unknown codes.

import { getErrorMessage, AlcoreErrorCodes } from '@alviere/core';

getErrorMessage(AlcoreErrorCodes.BANK_ACCOUNT_ALREADY_EXISTS);
// → 'Bank account already exists'

Recommended error handling pattern

import { AlcoreApiError, AlcoreErrorCodes, isCriticalError, getErrorMessage } from '@alviere/core';

async function safeServiceCall<T>(fn: () => Promise<T>): Promise<T | null> {
  try {
    return await fn();
  } catch (err) {
    if (!(err instanceof AlcoreApiError)) throw err;

    const code = err.code;

    if (isCriticalError(code)) {
      // Session expired or auth failed — force re-login
      if (code === AlcoreErrorCodes.INVALID_JWT || code === AlcoreErrorCodes.AUTH_FAILED) {
        redirectToLogin();
      } else {
        showFatalError(getErrorMessage(code));
      }
      return null;
    }

    // Non-critical: show inline message
    showFieldError(getErrorMessage(code));
    return null;
  }
}

Types & Enums