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

# Error Handling

> Use the Vaultkit SDK’s typed errors to build resilient agents and human-in-the-loop workflows.

# Error Handling

The SDK wraps every failure in a typed `VaultkitError` subclass so you can decide how the agent should respond. Catch these errors around your calls to `connect()` or inside the logic that executes tools.

## Error classes

| Error                 | When it is thrown                                                                                                        | Typical response                                                                                |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| `AuthenticationError` | Missing/invalid API key, conflicting `vaultId`/`featureMappingId`, revoked credentials, or forbidden provider selection. | Rotate credentials, prompt the user to reconnect, or fall back to a limited experience.         |
| `ConnectionError`     | Vaultkit service is unreachable or network retries were exhausted.                                                       | Retry with backoff, surface a status badge, or queue work for later.                            |
| `ToolError`           | A tool failed to execute (for example invalid parameters returned by the LLM).                                           | Show the error to the end user or ask the agent to reformulate the request.                     |
| `ApprovalError`       | The tool requires a human decision before continuing.                                                                    | Pause the workflow, notify an operator, or poll the approval endpoint until a decision is made. |

All error classes extend `VaultkitError`, which exposes `message`, `code`, and an optional `statusCode`.

## Pattern example

```ts theme={null}
import {
  createVaultkitClient,
  AuthenticationError,
  ConnectionError,
  ToolError,
  ApprovalError,
} from "@vaultkit/ai-sdk";

export async function runAgent(prompt: string) {
  const vaultkit = createVaultkitClient({
    apiKey: process.env.VAULTKIT_API_KEY!,
    userId: "customer-123",
    vaultId: process.env.VAULTKIT_VAULT_ID,
  });

  try {
    await vaultkit.connect();
    const response = await agentRunner({ prompt, tools: vaultkit.tools });
    return { ok: true, data: response };
  } catch (error) {
    if (error instanceof AuthenticationError) {
      return { ok: false, reason: "invalid-credentials" };
    }

    if (error instanceof ApprovalError) {
      queueApprovalNotification(error);
      return { ok: false, reason: "awaiting-approval" };
    }

    if (error instanceof ConnectionError) {
      scheduleRetry({ prompt });
      return { ok: false, reason: "retrying" };
    }

    if (error instanceof ToolError) {
      return { ok: false, reason: "tool-failure", details: error.message };
    }

    throw error; // bubble up unexpected failures
  } finally {
    await vaultkit.disconnect();
  }
}
```

## Logging helpers

Pass a `log` function to `createVaultkitClient` to receive structured messages about connection attempts, discovered tools, timeouts, and retries. This makes it easy to correlate application logs with Vaultkit’s telemetry in production.

```ts theme={null}
const vaultkit = createVaultkitClient({
  apiKey,
  userId,
  vaultId,
  log: (level, message, meta) => {
    logger[level]({ message, ...meta, source: "vaultkit" });
  },
});
```

Pair the SDK logs with the Vaultkit dashboard → Tool Telemetry screen to monitor the full lifecycle of each request.