Error Handling - Oak Network

Contract calls can revert with on-chain errors. The SDK decodes raw revert data into typed error classes with decoded arguments and human-readable recovery hints.

Decoding revert errors

Use parseContractError() to decode raw revert data from a failed transaction or simulation:

import { parseContractError, getRevertData } from '@oaknetwork/contracts-sdk';

function handleError(err) {
  // If the error is already a typed SDK error (thrown by simulate methods)
  if (typeof err?.recoveryHint === 'string') {
    console.error('Reverted:', err.name);
    console.error('Args:', err.args);
    console.error('Hint:', err.recoveryHint);
    return;
  }
  // Otherwise extract raw revert hex from the viem error chain and decode it
  const revertData = getRevertData(err);
  const parsed = parseContractError(revertData ?? '');
  if (parsed) {
    console.error('Reverted:', parsed.name);
    console.error('Args:', parsed.args);
    if (parsed.recoveryHint) console.error('Hint:', parsed.recoveryHint);
    return;
  }
  console.error('Unknown error:', err.message);
}

try {
  const txHash = await factory.createCampaign({ ... });
} catch (err) {
  handleError(err);
}

getRevertData(error)

Walks the error cause chain and extracts the first 0x-prefixed hex string from error.data. Returns null if no revert data is found.

parseContractError(revertData)

Takes a hex string (selector + encoded args) and returns a typed ContractErrorBase or null if the error is not recognized.

ContractErrorBase

All typed errors implement this interface:

interface ContractErrorBase {
  readonly name: string;                    // e.g. "GlobalParamsUnauthorized"
  readonly args: Record<string, unknown>;   // decoded error arguments
  readonly recoveryHint?: string;           // human-readable suggestion
}

Simulation with error decoding

Use simulateWithErrorDecode() to wrap a simulateContract call. It catches reverts, decodes them, and re-throws as typed SDK errors:

import { simulateWithErrorDecode } from '@oaknetwork/contracts-sdk';

try {
  await simulateWithErrorDecode(() =>
    gp.simulate.enlistPlatform(platformHash, admin, fee, adapter)
  );
  // Safe to send
  const txHash = await gp.enlistPlatform(platformHash, admin, fee, adapter);
} catch (err) {
  if ('recoveryHint' in err) {
    console.error(err.name, '-', err.recoveryHint);
  }
}

Or use the simulate namespace directly on any entity — it already throws typed errors:

try {
  await gp.simulate.enlistPlatform(platformHash, admin, fee, adapter);
} catch (err) {
  console.error(err.name, err.recoveryHint);
}

Error types by contract

GlobalParams errors

Error	When it occurs	Recovery hint
`GlobalParamsInvalidInput`	Invalid address, fee, or bytes input	Check addresses, fee percent, and platform bytes
`GlobalParamsPlatformAlreadyListed`	Enlisting a platform that exists	Use a different platform hash or update
`GlobalParamsPlatformNotListed`	Operating on unlisted platform	Enlist the platform first
`GlobalParamsUnauthorized`	Caller is not protocol admin	Use the admin account
`GlobalParamsPlatformAdminNotSet`	Platform admin not configured	Set the platform admin address first
`GlobalParamsPlatformFeePercentIsZero`	Zero fee percent	Fee must be greater than zero
`GlobalParamsCurrencyHasNoTokens`	Currency has no accepted tokens	Add at least one token
`GlobalParamsTokenNotInCurrency`	Token not in currency list	Use an approved token
`GlobalParamsPlatformLineItemTypeNotFound`	Line item type not registered	Register the line item type first
`GlobalParamsPlatformDataAlreadySet`	Data key already exists	Use a different key
`GlobalParamsPlatformDataNotSet`	Data key not found	Add platform data first
`GlobalParamsPlatformDataSlotTaken`	Data slot occupied	Use a different key
`GlobalParamsCurrencyTokenLengthMismatch`	Array length mismatch	Match currencies and tokens array lengths

CampaignInfoFactory errors

Error	When it occurs	Recovery hint
`CampaignInfoFactoryInvalidInput`	Invalid campaign creation params	Check creator, platforms, and data
`CampaignInfoFactoryPlatformNotListed`	Selected platform not in GlobalParams	Enlist the platform first
`CampaignInfoFactoryCampaignWithSameIdentifierExists`	Duplicate identifier hash	Use a different identifier
`CampaignInfoFactoryCampaignInitializationFailed`	Clone failed to initialize	Check campaign data and implementation
`CampaignInfoInvalidTokenList`	Currency tokens don’t match GlobalParams	Fix token list for campaign currency

CampaignInfo errors

Error	When it occurs	Recovery hint
`CampaignInfoInvalidInput`	Invalid update input	Check input values
`CampaignInfoIsLocked`	Campaign is locked	Cannot modify locked campaigns
`CampaignInfoUnauthorized`	Caller not authorized	Use the campaign owner account
`CampaignInfoPlatformNotSelected`	Platform not selected	Select the platform first
`CampaignInfoPlatformAlreadyApproved`	Platform already approved	Platform is already set up
`CampaignInfoInvalidPlatformUpdate`	Invalid platform update	Check platform hash and data

PaymentTreasury errors

Error	When it occurs	Recovery hint
`PaymentTreasuryInvalidInput`	Invalid payment parameters	Check payment data
`PaymentTreasuryPaymentAlreadyExist`	Duplicate payment ID	Use a unique payment ID
`PaymentTreasuryPaymentNotExist`	Payment not found	Check the payment ID
`PaymentTreasuryPaymentAlreadyConfirmed`	Payment already confirmed	Cannot re-confirm
`PaymentTreasuryPaymentAlreadyExpired`	Payment expired	Create a new payment
`PaymentTreasuryPaymentNotConfirmed`	Payment not yet confirmed	Confirm the payment first
`PaymentTreasuryPaymentNotClaimable`	Payment does not meet refund eligibility	May not be confirmed, expired, or claim window not reached
`PaymentTreasuryTokenNotAccepted`	Token not accepted	Use an accepted token
`PaymentTreasuryUnAuthorized`	Caller not authorized	Use authorized account
`PaymentTreasuryCampaignInfoIsPaused`	Campaign is paused	Unpause the campaign first
`PaymentTreasurySuccessConditionNotFulfilled`	Goal not reached	Goal amount must be reached before withdrawing
`PaymentTreasuryCryptoPayment`	Wrong flow for crypto payment	Use `processCryptoPayment()` instead
`PaymentTreasuryInsufficientBalance`	Insufficient token balance	Fund the account
`PaymentTreasuryInsufficientFundsForFee`	Insufficient funds for withdrawal fee	Ensure treasury has enough balance for the fee
`PaymentTreasuryFeeNotDisbursed`	Fees not yet disbursed	Call `disburseFees()` first
`PaymentTreasuryAlreadyWithdrawn`	Already withdrawn	Cannot withdraw twice
`PaymentTreasuryExpirationExceedsMax`	Payment expiration too long	Use a shorter expiration time
`PaymentTreasuryClaimWindowNotReached`	Claim attempted too early	Wait until the claimableAt timestamp
`PaymentTreasuryNoFundsToClaim`	No funds available	No refundable funds

AllOrNothing errors

Error	When it occurs	Recovery hint
`AllOrNothingInvalidInput`	Invalid parameters	Check input values
`AllOrNothingNotSuccessful`	Goal not met	Cannot withdraw — goal was not reached
`AllOrNothingNotClaimable`	Refund not available	Refund conditions not met
`AllOrNothingRewardExists`	Duplicate reward name	Use a different reward name
`AllOrNothingTokenNotAccepted`	Token not accepted	Use an accepted token
`AllOrNothingUnAuthorized`	Caller not authorized	Use authorized account
`AllOrNothingFeeAlreadyDisbursed`	Fees already disbursed	Already processed
`AllOrNothingFeeNotDisbursed`	Fees not disbursed	Call `disburseFees()` first
`AllOrNothingTransferFailed`	Token transfer failed	Check balances and allowances
`TreasurySuccessConditionNotFulfilled`	Goal not met	Goal amount must be reached before withdrawing

KeepWhatsRaised errors

Error	When it occurs	Recovery hint
`KeepWhatsRaisedInvalidInput`	Invalid parameters	Check input values
`KeepWhatsRaisedConfigLocked`	Configuration is locked	Wait for lock period to expire
`KeepWhatsRaisedDisabled`	Feature is disabled	Cannot perform this operation
`KeepWhatsRaisedAlreadyEnabled`	Already enabled	Already configured
`KeepWhatsRaisedAlreadyClaimed`	Already claimed	Cannot claim twice
`KeepWhatsRaisedAlreadyWithdrawn`	Already withdrawn	Cannot withdraw twice
`KeepWhatsRaisedNotClaimable`	Not claimable	Conditions not met for claim
`KeepWhatsRaisedNotClaimableAdmin`	Admin claim conditions not met	Ensure campaign is in the correct state
`KeepWhatsRaisedRewardExists`	Duplicate reward name	Use a different reward name
`KeepWhatsRaisedTokenNotAccepted`	Token not accepted	Use an accepted token
`KeepWhatsRaisedUnAuthorized`	Caller not authorized	Use authorized account
`KeepWhatsRaisedPledgeAlreadyProcessed`	Pledge already processed	Cannot re-process
`KeepWhatsRaisedInsufficientFundsForFee`	Insufficient funds for fee	Ensure sufficient balance
`KeepWhatsRaisedInsufficientFundsForWithdrawalAndFee`	Insufficient funds for withdrawal + fee	Reduce withdrawal or wait for more pledges
`KeepWhatsRaisedDisbursementBlocked`	Disbursement blocked	Conditions not met

TreasuryFactory errors

Error	When it occurs	Recovery hint
`TreasuryFactoryUnauthorized`	Caller not authorized	Use authorized account
`TreasuryFactoryInvalidAddress`	Invalid contract address	Check the address
`TreasuryFactoryInvalidKey`	Invalid implementation key	Check implementation ID
`TreasuryFactoryImplementationNotSet`	Implementation not registered	Register the implementation first
`TreasuryFactoryImplementationNotSetOrApproved`	Not set or not approved	Register and approve the implementation
`TreasuryFactoryTreasuryCreationFailed`	Treasury deploy failed	Check campaign and implementation
`TreasuryFactoryTreasuryInitializationFailed`	Treasury init failed	Check configuration
`TreasuryFactorySettingPlatformInfoFailed`	Platform info update failed	Check platform configuration

Shared errors (cross-contract)

Error	When it occurs	Recovery hint
`AccessCheckerUnauthorized`	Generic access control failure	Check permissions
`AdminAccessCheckerUnauthorized`	Not an admin	Only admins can do this
`CurrentTimeIsGreater`	Timestamp in the past	Provide a future timestamp
`CurrentTimeIsLess`	Time not yet reached	Wait until the specified time
`CurrentTimeIsNotWithinRange`	Outside allowed time window	Operation only valid in range
`TreasuryCampaignInfoIsPaused`	Campaign is paused	Unpause the campaign first
`TreasuryFeeNotDisbursed`	Fees not disbursed	Call `disburseFees()` first
`TreasuryTransferFailed`	Token transfer failed	Check balances and allowances

Checking error types

import {
  GlobalParamsPlatformNotListedError,
  CampaignInfoFactoryInvalidInputError,
} from '@oaknetwork/contracts-sdk';

try {
  await factory.createCampaign(params);
} catch (err) {
  if (err instanceof GlobalParamsPlatformNotListedError) {
    console.error('Platform not listed:', err.args.platformHash);
  } else if (err instanceof CampaignInfoFactoryInvalidInputError) {
    console.error('Invalid input:', err.recoveryHint);
  }
}

getRecoveryHint

Convenience function to extract the recovery hint from any typed error:

import { getRecoveryHint } from '@oaknetwork/contracts-sdk';

const hint = getRecoveryHint(err);
if (hint) console.log('Suggestion:', hint);

​Decoding revert errors

​getRevertData(error)

​parseContractError(revertData)

​ContractErrorBase

​Simulation with error decoding

​Error types by contract

​GlobalParams errors

​CampaignInfoFactory errors

​CampaignInfo errors

​PaymentTreasury errors

​AllOrNothing errors

​KeepWhatsRaised errors

​TreasuryFactory errors

​Shared errors (cross-contract)

​Checking error types

​getRecoveryHint