Skip to main content

​
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

ErrorWhen it is thrownTypical response
AuthenticationErrorMissing/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.
ConnectionErrorVaultkit service is unreachable or network retries were exhausted.Retry with backoff, surface a status badge, or queue work for later.
ToolErrorA 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.
ApprovalErrorThe 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.