Error Handling - WalletSuite

SDK calls throw ApiError — a transport-layer wrapper around the response returned by the WalletSuite API. The wrapper carries the HTTP call metadata (URL, method, status, retry attempt). The canonical error contract — category, code, message, requiredAction — is documented in Structured Errors. Parse err.bodySnippet as JSON to reach it.

`ApiError` fields

Field	Type	What it carries
`message`	`string`	Human-readable summary (same as `Error.message`)
`url`	`string`	Full request URL that failed
`method`	`string`	HTTP verb (`GET`, `POST`, …)
`status`	`number \| undefined`	HTTP status code. Undefined means the request never reached the server — a transport-level failure (timeout, DNS, `ECONNREFUSED`)
`bodySnippet`	`string \| undefined`	Truncated raw response body. Contains the structured error JSON when the server returned one
`attempt`	`number`	Which retry attempt failed (1-indexed). Useful for correlating with logs
`causeErr`	`unknown`	Underlying error object, if any (`fetch` failure cause, etc.)

Reading the structured error

Wrap every SDK call in try / catch. Check err.bodySnippet for the structured payload when the server responded:

import { WalletSuiteSDK, ApiError } from "@walletsuite/wallet-sdk";

try {
  await sdk.api.getPriceBySymbol("ETH", "USD");
} catch (err) {
  if (err instanceof ApiError && err.bodySnippet) {
    try {
      const payload = JSON.parse(err.bodySnippet);
      // payload: { category, code, message, requiredAction? }
      // See /core-concepts/structured-errors for the full taxonomy.
    } catch {
      // bodySnippet was non-JSON — fall through to transport handling
    }
  }
}

See Structured Errors → From the SDK for a switch on category that covers every recovery path.

Transport-level failures

When err.status is undefined, the request never reached the server. Common causes:

Network timeout
DNS resolution failure
ECONNREFUSED from a local proxy
TLS handshake error

In this case err.bodySnippet is also undefined and there is no structured payload to parse — the retry policy should treat it like an upstream category error (retry with backoff, then surface to the user).

Debug logging

Enable debug: true during development to log request and response details to stdout:

const sdk = new WalletSuiteSDK({
  env: "prod",
  apiKey: process.env.WALLETSUITE_API_KEY!,
  debug: true,
});

Never leave debug: true enabled in production — logs may include URLs that carry sensitive path parameters.

Structured Errors — canonical category / code / requiredAction taxonomy
Security Best Practices → Logging — what to log and what to redact

​ApiError fields

​Reading the structured error

​Transport-level failures

​Debug logging

​Related

`ApiError` fields

Reading the structured error

Transport-level failures

Debug logging

Related