Error Handling - XentFi API Documentation

MCP Tools and the x402 Facilitator SDK report failures differently — tool calls return a structured error result, the facilitator client throws. Pick your track below.

MCP Tools
x402 Facilitator

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.

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. A denied payment comes back as a tool error (not a crash), with code: "POLICY_DENIED" and a hint pointing at xentfi_get_policy.

Well-behaved agents call xentfi_get_policy proactively before a large or unusual payment, rather than waiting to be denied.

Authentication failures

A 401/403 from any tool comes back with a hint to check the agent API key. Common causes:

Missing XENTFI_API_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 essentials/agent for every client’s exact config.

Revoked or suspended agent

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

Missing organization ID

Market-data tools (xentfi_list_blockchains, xentfi_list_tokens, price lookups) require orgId in addition to the API key — set XENTFI_ORG_ID.

Programmatic use (outside of tool handlers)

Using XentfiClient directly raises real exceptions instead of a JSON tool result:

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

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

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

verify() and settle() throw on failure rather than returning a falsy result — there is no { isValid: false } shape to check.

Error classes

Class	When it’s thrown
`X402FacilitatorConfigError`	Missing required config (`apiKey` or `orgId`) — thrown synchronously by the constructor, before any network call.
`X402FacilitatorNetworkError`	The network request itself never completed (DNS failure, timeout, connection refused). Automatically retried — see below.
`X402FacilitatorError`	The facilitator returned an unexpected HTTP status. Carries a `.statusCode` property.

import {
  X402FacilitatorClient,
  X402FacilitatorError,
  X402FacilitatorConfigError,
  X402FacilitatorNetworkError,
} from "@xentfi/x402-facilitator-sdk";

try {
  const facilitator = new X402FacilitatorClient({ apiKey, orgId });
  await facilitator.verify(payload, requirement);
} catch (err) {
  if (err instanceof X402FacilitatorConfigError) {
    // apiKey/orgId missing — a setup bug, fix before deploying
  } else if (err instanceof X402FacilitatorNetworkError) {
    // exhausted retries against a genuine network failure
  } else if (err instanceof X402FacilitatorError) {
    console.log(err.statusCode, err.message);
  }
}

HTTP status mapping

Code	Meaning
`402`	Payment or verification failed (invalid signature, expired authorization, amount/recipient mismatch).
`400`	Bad request or validation error.
`401`	Authentication error — invalid or missing `apiKey`/`orgId`.
`403`	Authorization error — credentials valid but insufficient permission.
`404`	Resource not found.
`500`	Internal server error.

A 402 from /verify or /settle is a normal, expected outcome for an invalid or expired payment — surface err.message back to the payer in your own 402 challenge response’s error field (see essentials/x402).

Automatic retries

Requests are retried automatically on X402FacilitatorNetworkError with exponential backoff and jitter (immediate, then ~250ms, then ~500ms). Requests that do get a response — including 402s — are not retried automatically.

Common scenarios

402 from verify() — invalid signature

Usually a wrong Eip3009TokenDomain (see essentials/x402) or a payload tampered with in transit.

402 from verify() — expired authorization

validBefore has passed. Have the payer re-sign a fresh authorization.

402 from settle() — nonce already used

The same (from, nonce) pair was already submitted on-chain — expected on a genuine retry of an already-settled payment if you reuse deterministic nonces.

401 Unauthorized

Invalid or revoked apiKey/orgId — verify both against the dashboard.

Both map onto the platform-wide conventions in API Reference: Error Handling.

​Tool-level error shape

​Policy denials

​Authentication failures

​Programmatic use (outside of tool handlers)

​Error classes

​HTTP status mapping

​Automatic retries

​Common scenarios

Tool-level error shape

Policy denials

Authentication failures

Programmatic use (outside of tool handlers)

Error classes

HTTP status mapping

Automatic retries

Common scenarios