Skip to main content
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": "PASSPHRASE_NOT_SET",
  "message": "WALLETSUITE_PASSPHRASE secret is not configured.",
  "requiredAction": "Set the WALLETSUITE_PASSPHRASE secret in the agent's secret store and call create_wallet again. The passphrase encrypts your wallet share at rest."
}

​
Error Categories

CategoryWhere it appearsMeaningWhat the caller should do
validationSDK + MCPBad input — address format, missing field, invalid amountFix the input and retry
upstreamSDK + MCPBackend API or RPC failure, possibly transientRetry with exponential backoff
flowMCP onlyPrerequisite missing — wallet not created, signing passphrase not setExecute the requiredAction first, then retry
authSDK + MCPAPI key invalid, missing, or unauthorizedStop — tell the user to configure credentials
limitSDK + MCPRate or quota exceededBack off, retry after the rate limit window
not_availableSDK + MCPFeature not enabled for this API keyInform 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 (MPC signing layer, policy engine, Zod pre-validation, tool dispatch). Not returned by the REST API — SDK callers do not encounter these.

​
Validation Errors

CodeSourceWhen It Happens
INVALID_ADDRESSMCPAddress fails Zod format check for the specified chain (e.g., not 0x-prefixed for EVM) — raised before the API call
INVALID_AMOUNTMCPHuman-readable amount is not a positive decimal string
INVALID_AMOUNT_WEIMCPWei amount is not a positive integer string
MISSING_TOKEN_CONTRACTMCPToken transfer attempted with a symbol but no contract address — use resolve_asset first
INVALID_PARAMSMCPZod schema validation failed on tool input
BAD_REQUESTAPIBackend returned 400 — check the request parameters
NOT_FOUNDAPIBackend returned 404 — the resource does not exist

​
Flow Errors — MCP only

Flow errors signal prerequisites missing in the MPC signing layer, policy engine, or MCP environment. They are raised by MCP orchestration and never returned by the REST API, so SDK callers do not encounter them.
CodeWhen It HappensRequired Action
WALLET_ALREADY_EXISTScreate_wallet called with a name that already exists locallyChoose a different walletName, or delete the existing wallet first
PASSPHRASE_NOT_SETcreate_wallet called without the signing passphrase configuredSet the WALLETSUITE_PASSPHRASE secret, then retry
WRONG_PASSPHRASEThe configured passphrase cannot unlock the local shareUpdate WALLETSUITE_PASSPHRASE to match the passphrase used when this wallet was created
MPC_OWNER_MODE_REQUIREDAn owner-only tool (create_wallet, create_custom_policy, or create_agent_api_key) called while not in owner modeRestart the MCP server with MPC_AUTH_MODE=owner, then retry
MISSING_POLICY_GUARDRAILcreate_custom_policy called with no constraint suppliedSupply at least one of allowlist, maxValueEth, or rateLimitPerHour, then retry
MOONPAY_CONFIG_REQUIREDprepare_onramp called without MoonPay env varsSet MOONPAY_API_KEY and MOONPAY_SECRET_KEY

​
Auth Errors

CodeSourceWhen It Happens
UNAUTHORIZEDAPIAPI key is missing or invalid (backend returned 401)
FORBIDDENAPIAPI key is valid but not authorized for this operation (backend returned 403)

​
Upstream Errors

CodeSourceWhen It Happens
SERVER_ERRORAPIBackend returned 500, 502, or 503
TIMEOUTAPIRequest exceeded the timeout (default 60s)
NETWORKAPIDNS or connection failure
TX_COMPILER_*APITransaction compilation failed at the backend
SIMULATION_FAILEDAPITransaction simulation at the backend failed
INVALID_BACKEND_RESPONSEMCPBackend response did not match the expected schema (MCP client-side guard)

​
Limit and Feature Errors

CodeSourceWhen It Happens
RATE_LIMITEDAPIBackend returned 429 — too many requests
PLAN_RESTRICTEDAPIBackend returned 403 — feature not enabled on your API key
FEATURE_GATEDMCPMCP tool classified as not-available for your plan (surfaces PLAN_RESTRICTED to the agent as a not_available category error)

​
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:
  1. Check category
  2. If flow — execute the requiredAction, then retry the original request
  3. If validation — fix the input based on the message, then retry
  4. If upstream — retry with exponential backoff (3 attempts, then surface to user)
  5. If auth — stop and ask the user to fix their credentials
  6. If limit — wait and retry
  7. 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 only see the API-source categories: validation (from the backend, not Zod), auth, upstream, limit, and not_available. The flow category is MCP-only and will 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.