Error Handling

Tool calls never throw raw exceptions back to the MCP client. Every failure is returned as a structured tool result with isError: true, so the calling agent can reason about it and decide what to do next — retry, adjust arguments, or explain the failure to a human.

Tool-level error shape

{
    "error": true,
    "status": 409,
    "code": "POLICY_DENIED",
    "message": "Transaction exceeds daily limit of $500.00",
    "requestId": "req_123e4567",
    "hint": "The agent's spend policy blocked this transaction (limit, allowlist, or time-window restriction). Call xentfi_get_policy to inspect current limits and spend."
}

Field	Description
`status`	The underlying HTTP status from the XentFi API.
`code`	Machine-readable error code, matching API error codes.
`message`	Human-readable description, safe to show to an end user.
`requestId`	Use this when contacting support — see Request ID Tracking.
`hint`	Only present for auth failures and policy denials — a next step the agent can act on.

Policy denials

xentfi_create_payment is checked against the agent’s Policy server-side on every call, regardless of what the client validated beforehand. A denied payment comes back as a tool error (not a crash), with code: "POLICY_DENIED" and a hint pointing the agent at xentfi_get_policy to inspect current limits and spend before retrying with different parameters.

Well-behaved agents call xentfi_get_policy proactively before a large or unusual payment, rather than waiting to be denied. It’s a cheap read and avoids a wasted round trip.

Authentication failures

A 401/403 from any tool comes back with hint: "Check that the agent API key is valid and has not been revoked or suspended." Common causes:

Missing XENTFI_AGENT_KEY

The stdio server logs Missing XentFi agent API key to stderr and every tool call fails identically. Fix the env block in your MCP client’s config — see the client-specific guide (e.g. Claude Desktop).

Revoked or suspended agent

xentfi_get_agent_info will show status: "SUSPENDED" or "REVOKED". Re-enable the agent or issue a new key from the dashboard.

Wrong environment's key

A sandbox key against production XENTFI_BASE_URL (or vice versa) returns 401. Double check XENTFI_BASE_URL matches the environment the key was issued in.

Programmatic use (outside of tool handlers)

If you’re using XentfiClient directly rather than through the MCP tool layer, failures raise real exceptions instead of a JSON tool result:

import { XentfiClient, XentfiApiError, XentfiConfigError } from "@xentfi/mcp-server";

const xentfi = new XentfiClient({ apiKey: process.env.XENTFI_AGENT_KEY });

try {
  await xentfi.post("/agent-self/payments", { body: { /* ... */ } });
} catch (err) {
  if (err instanceof XentfiApiError) {
    console.log(err.status, err.code, err.requestId);
    if (err.isPolicyDenied) {
      // check xentfi_get_policy / GET /agent-self/policy
    }
    if (err.isAuthError) {
      // rotate or re-check the API key
    }
  } else if (err instanceof XentfiConfigError) {
    // missing XENTFI_AGENT_KEY — a client setup bug, not an API response
  }
}

See API Reference: Error Handling for the full HTTP status and error-code tables that these map to.

Getting Started

Client Integrations

Deployment

Reference

Tool-level error shape

Policy denials

Authentication failures

Programmatic use (outside of tool handlers)

​Tool-level error shape

​Policy denials

​Authentication failures

​Programmatic use (outside of tool handlers)

Tool-level error shape

Policy denials

Authentication failures

Programmatic use (outside of tool handlers)