Skip to main content
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

FieldTypeWhat it carries
messagestringHuman-readable summary (same as Error.message)
urlstringFull request URL that failed
methodstringHTTP verb (GET, POST, …)
statusnumber | undefinedHTTP status code. Undefined means the request never reached the server — a transport-level failure (timeout, DNS, ECONNREFUSED)
bodySnippetstring | undefinedTruncated raw response body. Contains the structured error JSON when the server returned one
attemptnumberWhich retry attempt failed (1-indexed). Useful for correlating with logs
causeErrunknownUnderlying 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.