> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xentfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling

> How @xentfi/mcp-server surfaces API failures and policy denials to an MCP client.

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

```json theme={null}
{
    "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](/api-reference/errors#error-codes).              |
| `message`   | Human-readable description, safe to show to an end user.                                                 |
| `requestId` | Use this when contacting support — see [Request ID Tracking](/api-reference/errors#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.

<Tip>
  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.
</Tip>

## 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:

<AccordionGroup>
  <Accordion title="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](/agent/claude-desktop)).
  </Accordion>

  <Accordion title="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](https://dashboard.xentfi.com).
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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:

```ts theme={null}
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](/api-reference/errors) for the full HTTP status and error-code tables that these map to.