Skip to main content
Use this page when your agent is connected to the hosted platform at https://mcp.walletsuite.io but something is not working as expected.
Every response carries a structured WalletSuiteError — category, code, message, plus a requiredAction on flow errors. Check category first; it tells the agent what class of action to take. See Structured Errors.

​
Authentication (401 / 403)

An auth-category error means the bearer is bad or the credential behind it is not entitled to what you asked for.

​
Symptom: requests start failing after a few minutes

The short-lived token expired. Fix:
  • re-authorize with the agent’s key to get a fresh token — see Connect your agent
  • refresh proactively before the token expires rather than waiting for the first 401

​
Symptom: UNAUTHORIZED on the token exchange itself

The agent’s key is missing, malformed, or revoked. Check:
  • your server authorizes with the agent’s key, not the model
  • the credential has not been revoked in the dashboard — revoking it cuts the agent off immediately
Fix:
  • provision a fresh key and rotate it into your server’s secret store — the raw key never reaches the model, a prompt, or a downstream MCP call

​
Symptom: FORBIDDEN on an otherwise valid call

The token is valid but its authority does not cover the operation — the agent’s tool profile or scopes don’t include it. See Execution Levels.

​
A tool is missing

​
Symptom: a tool you expected is not in the MCP schema

A tool the agent cannot reach is never registered — that absence is the prompt-injection boundary, not a bug. A tool appears only if the agent’s tool profile and granted scopes both allow it — see Execution Levels. Check:
  • the agent’s execution level is high enough — read, prepare, execute, or governed
  • the agent’s granted scopes cover the tool (e.g. signing tools require wallets:sign)
  • the tool is within the agent’s granted tool profile
Fix:
  • raise the agent’s tool profile or granted scopes server-side, then reconnect the agent — see Connect your agent

​
An operation is denied

​
Symptom: a signing call comes back denied

A denial is a deterministic policy decision, not a transient failure. Through the hosted MCP endpoint it surfaces as a flow error whose message carries the decision reason and whose requiredAction names the next step. The same request denies again until the request or the policy changes — do not blindly retry. Common reasons (full list):
  • chain_not_entitled — the intent’s chain is outside the chains you’re entitled to. Sign on an entitled chain, or have it added to your plan.
  • no_matching_rule — the org allowlist is armed and no active rule admits this operation. Adjust the request to satisfy a rule, or have an admin add one.
  • unclassified_operation — the operation could not be typed; deny-by-default rejects it. Use a supported operation type.
See Policy Gates for the rule model. Quote the policyDecisionId from the response when raising a support ticket.

​
Symptom: a flow error before any signing happens

A prerequisite is missing. The requiredAction in the response is the concrete next step. Fix:
  • execute the requiredAction first, then retry the original request

​
Feature not available

​
Symptom: a tool exists but calls return a not-available error

The capability is not enabled for your plan — a not_available-category error. Fix:
  • confirm whether the capability is on your plan
  • fall back to the read and prepare surface when possible

​
Still stuck?

If the problem persists, contact the WalletSuite team at support@walletsuite.io.