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

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.

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.

Overview

Welcome

Vaultkit SDK

Error Handling

Error Handling

Error classes

Pattern example

Logging helpers

​Error Handling

​Error classes

​Pattern example

​Logging helpers

Error Handling

Error classes

Pattern example

Logging helpers