Error Handling

All errors thrown by the SDK extend BaseError, which provides a structured error chain and a walk() method for traversing nested causes.

`BaseError`

Every SDK error includes:

shortMessage — a concise description of what went wrong
details — additional context (e.g. HTTP status, URL)
metaMessages — optional array of hint strings
cause — the underlying error, if any

Walking the error chain

Use error.walk() to traverse the cause chain and find a specific error type:

import {
  BaseError,
  SimulateFailedError,
} from "@kontor/kontor-sdk";
 
try {
  // ... some SDK call
} catch (e) {
  if (e instanceof BaseError) {
    const simulateError = e.walk(
      (err) => err instanceof SimulateFailedError
    );
 
    if (simulateError) {
      console.log("Simulation failed:", simulateError.message);
    }
  }
}

Calling walk() with no arguments returns the deepest error in the chain.

Error Categories

Account

AccountNotFoundError — no account was provided for an action that requires one
PrivateKeyRequiredError — an HD key was used that doesn't contain a private key

Address

InvalidAddressError — the provided address is invalid

Chain

ChainNotFoundError — no chain was provided to the request
ChainMismatchError — the action's chain doesn't match the client's chain
ClientChainNotConfiguredError — the client was created without a chain
InvalidChainIdError — the chain ID is not recognized

Request & Transport

HttpRequestError — an HTTP request failed (includes status, url)
WebSocketRequestError — a WebSocket request failed
RpcRequestError — the RPC server returned an error (includes code, data)
TimeoutError — a request timed out
SocketClosedError — the WebSocket connection was closed unexpectedly
UrlRequiredError — a transport was created without a URL
HttpTransportRequiredError — the action requires an HTTP transport
WebSocketTransportRequiredError — the action requires a WebSocket transport

RPC

RpcError — base class for JSON-RPC errors (includes code)
UnknownRpcError — an RPC error with an unrecognized code

Simulation

SimulateFailedError — contract simulation returned no result (protocol error or insufficient gas)

WIT

WitFunctionNotFoundError — the function name doesn't exist in the WIT
WitFunctionOutputsNotFoundError — the function has no outputs to decode
WitEncodingLengthMismatchError — argument count doesn't match the WIT definition
InvalidWitEncodingTypeError — an unsupported WIT type was used for encoding
WitErrorInputsNotFoundError — error variant inputs could not be resolved

UTXO

NoUtxosProvidedError — no UTXOs were provided for a transaction that requires them

`instanceof` Checking

All errors can be checked with instanceof:

import {
  AccountNotFoundError,
  HttpRequestError,
} from "@kontor/kontor-sdk";
 
try {
  // ... some SDK call
} catch (e) {
  if (e instanceof AccountNotFoundError) {
    console.log("Please provide an account");
  }
 
  if (e instanceof HttpRequestError) {
    console.log("Request failed:", e.status, e.url);
  }
}

BaseError