> ## Documentation Index
> Fetch the complete documentation index at: https://docs.walletsuite.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling

> How the WalletSuite SDK surfaces errors: the ApiError wrapper, its call-metadata fields, and reaching the structured error contract.

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](/core-concepts/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:

```ts theme={null}
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](/core-concepts/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:

```ts theme={null}
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.

## Related

* [Structured Errors](/core-concepts/structured-errors) — canonical `category` / `code` / `requiredAction` taxonomy
* [Security Best Practices → Logging](/sdk/security-best-practices) — what to log and what to redact