Every error you can catch, by class and code

error.code is the machine contract: match on it in onError handlers and UI. Messages are human-readable and may change between versions. context carries the offending values, and the standard cause chain holds the underlying viem or Zama error. This page enumerates the installed build: 72 exported classes (38 on the root, 34 product-specific) and 69 codes.

Narrow with isTokenOpsSdkError#

isTokenOpsSdkError(error) checks a realm-global brand, so it still works when the SDK is duplicated in your bundle graph (hoisting issues, ESM and CJS loaded together, a route handler and a client bundle). instanceof works for the common case.

import { isTokenOpsSdkError } from "@tokenops/sdk";

function messageFor(err: unknown): string {
  if (!isTokenOpsSdkError(err)) return "Something went wrong.";
  switch (err.code) {
    case "TOKENOPS_WALLET_REJECTED":
    case "TOKENOPS_USER_REJECTED":
      return "Cancelled in the wallet.";
    case "TOKENOPS_WALLET_CHAIN_MISMATCH":
      return "Switch your wallet to the app's network.";
    case "TOKENOPS_OPERATOR_NOT_APPROVED":
      return "Approve the contract as an operator on your token first.";
    case "TOKENOPS_ACL_NOT_PROPAGATED":
      return "Access is still propagating. Retrying...";
    default:
      // A switch made exhaustive with a never check needs a case for every
      // code in the union, including the ones added on this line.
      return err.message; // human-readable; may change between versions
  }
}

The core palette#

Exported from the root @tokenops/sdk and re-exported by every product subpath, except MissingPeerDependencyError, which only the root and /fhe export. The code column is read from each class in the installed build.

The Zama error mapping#

Wherever the SDK calls @zama-fhe/sdk (product writes that encrypt, useDecryptedHandle, the airdrop campaign builders), it maps the thrown error to an SDK class and keeps the original as cause. Errors that are already TokenOpsSdkErrors pass through unchanged.

WalletChainMismatchError on every write#

Every SDK write, across all products and the /fhehelpers, refuses a wallet whose chain is not the public client's, before estimating gas and sending. The airdrop and faucet writes run their simulateContract preflight first, so a revert can surface before the chain check. The check is skipped when neither the request nor the wallet client carries a chain, or when the public client's chain id cannot be read. Since the airdrop contracts share their addresses across mainnet and Sepolia, a mismatched pair would otherwise simulate on one chain and send on the other. See Gas headroom for what happens after the check.

UnsupportedChainError: method and hint#

UnsupportedChainError takes optional method and hint, also set on its context, for surfaces narrower than the SDK. TestnetFaucetClient on mainnet says the faucet runs on Sepolia only and how to point the client there, instead of calling the chain unsupported by the whole SDK.

import { UnsupportedChainError } from "@tokenops/sdk";

if (err instanceof UnsupportedChainError) {
  // context.method and context.hint are set when the surface is narrower than the SDK,
  // for example the testnet faucet on mainnet.
  showBanner(err.context.hint ?? `Chain ${err.context.chainId} is not supported.`);
}

Product-specific classes#

Exported by one product subpath each. Their product error pages describe when each fires.

SingletonNotApprovedError (/fhe-disperse) is deprecated: nothing raises it any more, and a missing singleton approval is an OperatorNotApprovedError.

Every code#

The full TokenOpsSdkErrorCode union. A code with several classes is shared on purpose; branch on name or instanceof when you need to tell them apart.