Error handling

Some errors have a class HolyheldSDKError. The most helpful property of these errors is code. You can compare the code with the values in the HolyheldSDKErrorCode.

import { HolyheldSDKError, HolyheldSDKErrorCode } from '@holyheld/sdk';

const holyheldSDK = new HolyheldSDK({
  apiKey: process.env.HOLYHELD_SDK_API_KEY,
})

try {
  await holyheldSDK.evm.offRamp.topup(/* ... */);
} catch (error) {
  if (
    error instanceof HolyheldSDKError &&
    (error.code === HolyheldSDKErrorCode.UserRejectedTransaction ||
      error.code === HolyheldSDKErrorCode.UserRejectedSignature)
  ) {
    // it's OK
  } else {
    // it's NOT OK
  }
}

Types:

enum HolyheldSDKErrorCode {
  NotInitialized = 'HSDK_NI', // SDK is not initialized
  FailedInitialization = 'HSDK_FI', // cannot initialize SDK
  UnsupportedNetwork = 'HSDK_UN', // wallet active network is not supported by SDK
  InvalidTopUpAmount = 'HSDK_ITUA', // amount does not meet minimum or maximum allowed criteria
  InvalidOnRampAmount = 'HSDK_IORA', // amount does not meet minimum or maximum allowed criteria
  UnexpectedWalletNetwork = 'HSDK_UWN', // wallet active network is different from the selected network
  UserRejectedSignature = 'HSDK_RS', // user rejected the signature
  UserRejectedTransaction = 'HSDK_RT', // user rejected transaction
  FailedSettings = 'HSDK_FS', // cannot get settings
  FailedTagInfo = 'HSDK_FTI', // cannot get $holytag info
  FailedAddressInfo = 'HSDK_FAI', // cannot get address info
  FailedWalletBalances = 'HSDK_FWB', // cannot get wallet balance
  FailedConversion = 'HSDK_FC', // cannot estimate EUR to TOKEN, or TOKEN to EUR
  FailedTopUp = 'HSDK_FTU', // cannot complete top up
  FailedCreateOnRampRequest = 'HSDK_FCOR', // cannot create onramp request
  FailedOnRampRequest = 'HSDK_FOR', // fail execute onramp request with reason (for example not enough balance)
  FailedWatchOnRampRequestTimeout = 'HSDK_FwORT', // watch request timeout
  FailedWatchOnRampRequest = 'HSDK_FWORR', // fail to watch request status
  FailedConvertOnRampAmount = 'HSDK_FCORA', // cannot convert (estimate) EUR to TOKEN, or TOKEN to EUR
  FailedOnRampEstimation = 'HSDK_FORE', // cannot estimate the network fee amount and the final token amount
}

Error recovery categories

Not all errors are equal. Some are safe to retry immediately; others require user action; others are permanent failures.

Category	Error codes	Recovery
Retry automatically	HSDK_FS, HSDK_FTI, HSDK_FAI, HSDK_FWB, HSDK_FC, HSDK_FCOR, HSDK_FWORR, HSDK_FCORA, HSDK_FORE	Network or transient failures — retry with exponential backoff
Prompt the user to act	HSDK_RS, HSDK_RT, HSDK_UWN, HSDK_UN, HSDK_ITUA, HSDK_IORA, HSDK_FOR	User must take an action (switch network, adjust amount, confirm transaction)
Check before retrying	HSDK_FTU, HSDK_FwORT	Inspect state before retrying — the operation may have partially succeeded
Fix configuration	HSDK_NI, HSDK_FI	SDK is not correctly initialised — fix setup, then retry

Error code reference

Error code	Constant	Cause	Recommended action
HSDK_NI	NotInitialized	SDK method called before init() completed	Call await holyheldSDK.init() before any other SDK method
HSDK_FI	FailedInitialization	init() failed — invalid SDK API key or network unreachable	Check your SDK API key; retry init() after a short delay
HSDK_UN	UnsupportedNetwork	The wallet's current chain is not supported by the SDK	Prompt the user to switch to a supported network
HSDK_ITUA	InvalidTopUpAmount	Token amount is below the minimum or above the maximum EUR limit	Check getServerSettings() for current limits; adjust the amount
HSDK_IORA	InvalidOnRampAmount	EUR amount is below the minimum or above the maximum limit	Check getServerSettings() for current limits; adjust the amount
HSDK_UWN	UnexpectedWalletNetwork	Wallet is on a different chain than tokenNetwork	Prompt the user to switch their wallet to the correct network before calling topup
HSDK_RS	UserRejectedSignature	User dismissed the signature request in their wallet	Show a dismissible error — no retry needed unless the user wants to try again
HSDK_RT	UserRejectedTransaction	User dismissed the transaction confirmation in their wallet	Same as above — no retry needed unless the user chooses to
HSDK_FS	FailedSettings	getServerSettings() network request failed	Retry with exponential backoff; show "temporarily unavailable" if retries exhaust
HSDK_FTI	FailedTagInfo	getTagInfo() network request failed	Retry; if persistent, the holytag may not exist
HSDK_FAI	FailedAddressInfo	validateAddress() network request failed	Retry; if persistent, the address may not be eligible
HSDK_FWB	FailedWalletBalances	getWalletBalances() network request failed	Retry; check network connectivity
HSDK_FC	FailedConversion	convertTokenToEUR() or convertEURToToken() failed	Retry; if persistent, the token may not be supported on the selected network
HSDK_FTU	FailedTopUp	topup() failed to complete	Check error.message for detail; common causes: insufficient balance, unsupported token, network congestion
HSDK_FCOR	FailedCreateOnRampRequest	requestOnRamp() could not create the request	Retry; if persistent, check that the wallet address is eligible
HSDK_FOR	FailedOnRampRequest	On-ramp request rejected — e.g. insufficient card balance	Show the error message to the user; they may need to top up their Holyheld card
HSDK_FwORT	FailedWatchOnRampRequestTimeout	watchRequestId() timed out before user confirmed	The request may still be pending in the Holyheld app; inform the user and allow them to retry
HSDK_FWORR	FailedWatchOnRampRequest	watchRequestId() could not retrieve request status	Retry watchRequestId() with the same requestUid; the underlying request is still valid
HSDK_FCORA	FailedConvertOnRampAmount	On-ramp EUR/token conversion failed	Retry; if persistent, check the selected token and network
HSDK_FORE	FailedOnRampEstimation	On-ramp fee and expected amount estimation failed	Retry; if persistent, show a temporary estimation failure message