Structured Errors - WalletSuite

Every error from WalletSuite includes a category, code, and message. Errors in the flow category also include a requiredAction — a specific instruction for what the caller should do next. The contract is identical across the REST API, MCP tools, and the SDK — only the wrapper around it differs. Agents and integrators can recover programmatically instead of guessing.

Error Format

{
  "category": "validation",
  "code": "INVALID_ADDRESS",
  "message": "Address does not match expected format for ethereum"
}

For flow errors, a requiredAction is always included:

{
  "category": "flow",
  "code": "TRANSFER_NOT_PREPARED",
  "message": "No prepared transfer matches this request.",
  "requiredAction": "Call prepare_transfer to build the transfer, then submit the returned intent for signing."
}

Error Categories

Category	Where it appears	Meaning	What the caller should do
`validation`	SDK + MCP	Bad input — address format, missing field, invalid amount	Fix the input and retry
`upstream`	SDK + MCP	Backend API or RPC failure, possibly transient	Retry with exponential backoff
`flow`	MCP only	Prerequisite missing in the MCP signing flow — e.g. a transfer not yet prepared	Execute the `requiredAction` first, then retry
`auth`	SDK + MCP	API key invalid, missing, or unauthorized	Stop — tell the user to configure credentials
`limit`	SDK + MCP	Rate or quota exceeded	Back off, retry after the rate limit window
`not_available`	SDK + MCP	Feature not enabled for this API key	Inform the user the feature is not on their plan

Common Error Codes

Every error carries a code. The Source column tells you which layer raised it — and which surfaces can see it:

API — returned by the WalletSuite REST API. Visible to SDK and MCP callers alike.
MCP — raised by MCP tool orchestration (signing layer, policy engine, schema pre-validation, tool dispatch). Not returned by the REST API — SDK callers do not encounter these.

Validation Errors

Code	Source	When It Happens
`INVALID_ADDRESS`	MCP	Address fails the format check for the specified chain (e.g., not 0x-prefixed for EVM) — raised before the API call
`INVALID_AMOUNT`	MCP	Human-readable amount is not a positive decimal string
`INVALID_AMOUNT_WEI`	MCP	Wei amount is not a positive integer string
`MISSING_TOKEN_CONTRACT`	MCP	Token transfer attempted with a symbol but no contract address — use `resolve_asset` first
`INVALID_PARAMS`	MCP	Schema validation failed on tool input
`BAD_REQUEST`	API	Backend returned 400 — check the request parameters
`NOT_FOUND`	API	Backend returned 404 — the resource does not exist

Flow Errors — MCP only

Flow errors signal a missing prerequisite in the MCP signing flow — for example, a transfer that must be prepared before it can be signed. They are raised by MCP orchestration and never returned by the REST API, so SDK callers do not encounter them. (Policy denials are separate and reach every surface — see Policy Denials.)

Code	When It Happens	Required Action
`TRANSFER_NOT_PREPARED`	A sign or send request references a transfer that was never prepared	Call `prepare_transfer` to build the transfer, then submit the returned intent for signing
`INTENT_EXPIRED`	The prepared intent is no longer valid for signing	Call `prepare_transfer` again to build a fresh intent, then submit it

Policy denials are covered in Policy Denials below.

Auth Errors

Code	Source	When It Happens
`UNAUTHORIZED`	API	API key is missing or invalid (backend returned 401)
`FORBIDDEN`	API	API key is valid but not authorized for this operation (backend returned 403)

Upstream Errors

Code	Source	When It Happens
`SERVER_ERROR`	API	Backend returned 500, 502, or 503
`TIMEOUT`	API	Request exceeded the timeout (default 60s)
`NETWORK`	API	DNS or connection failure
`TX_COMPILER_*`	API	Transaction compilation failed at the backend
`SIMULATION_FAILED`	API	Transaction simulation at the backend failed
`INVALID_BACKEND_RESPONSE`	MCP	Backend response did not match the expected schema (MCP-side guard)

Limit and Feature Errors

Code	Source	When It Happens
`RATE_LIMIT_EXCEEDED`	API	Backend returned 429 — too many requests
`PLAN_RESTRICTED`	API	Backend returned 403 — feature not enabled on your API key
`FEATURE_GATED`	MCP	MCP tool classified as not-available for your plan (surfaces `PLAN_RESTRICTED` to the agent as a `not_available` category error)

Policy Denials

The policy engine evaluates every signing intent on every surface — MCP, SDK, and REST. When your organization’s policy denies an intent, WalletSuite records it in state denied with a decision reason and a policyDecisionId, and no signature is produced. On MCP this arrives as a flow error whose message carries the decision reason and whose requiredAction tells the agent how to proceed; SDK and REST callers receive the same decision reason and policyDecisionId. A policy denial is deterministic. The same request denies again until the request or the policy changes, so do not blindly retry. Quote the policyDecisionId when raising a support ticket.

Reason	When It Happens	What the caller should do
`chain_not_entitled`	The intent’s chain is outside the chains you’re entitled to	Sign on an entitled chain, or have the chain added to your plan
`no_matching_rule`	The org allowlist is armed and no active rule admits this operation	Adjust the request to satisfy an active rule, or have an admin add a rule
`unclassified_operation`	The org allowlist is armed and the operation could not be typed	Use a supported operation type

See Policy Gates for the rule model and Policy Decisions for the decision record on every intent.

Consuming errors

The same structured payload reaches the caller through two different wrappers. Pick the sub-section that matches your surface.

From an AI agent (MCP)

Every MCP tool response surfaces the structured error verbatim. The category field tells the agent what class of action to take; requiredAction (when present) gives a concrete next step. A well-behaved agent should:

Check category
If flow — execute the requiredAction, then retry the original request
If validation — fix the input based on the message, then retry
If upstream — retry with exponential backoff (3 attempts, then surface to user)
If auth — stop and ask the user to fix their credentials
If limit — wait and retry
If not_available — inform the user

From the SDK

SDK calls throw an ApiError wrapper. The structured payload lives in err.bodySnippet as a JSON string — parse it to reach category, code, and message. SDK callers see the API-source categories: validation (from the backend), auth, upstream, limit, and not_available — plus policy denials, which reach every surface with the decision reason and policyDecisionId. The flow category (MCP orchestration prerequisites) does not appear in SDK responses.

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

try {
  const balance = await sdk.api.getNativeBalance(address, "ethereum");
} catch (err) {
  if (err instanceof ApiError && err.bodySnippet) {
    try {
      const payload = JSON.parse(err.bodySnippet);
      switch (payload.category) {
        case "validation":    /* fix input, retry */         break;
        case "upstream":      /* retry with backoff */       break;
        case "auth":          /* check credentials */        break;
        case "limit":         /* wait and retry */           break;
        case "not_available": /* inform the user */          break;
      }
    } catch {
      // non-JSON body — transport-level failure (timeout, DNS, etc.)
    }
  }
}

For SDK-specific wrapper fields (url, method, status, attempt) and debug-logging behavior, see SDK Error Handling.

Design Principle

Errors are designed so agents can recover without human intervention whenever possible. A flow error with a requiredAction gives the agent a concrete next step — it does not need to guess or ask the user for help. Internal error details (internalMessage) are logged server-side but never included in the response sent to the LLM. The agent sees only what it needs to act on.

​Error Format

​Error Categories

​Common Error Codes

​Validation Errors

​Flow Errors — MCP only

​Auth Errors

​Upstream Errors

​Limit and Feature Errors

​Policy Denials

​Consuming errors

​From an AI agent (MCP)

​From the SDK

​Design Principle