Error Handling

Understand the Veto SDK error classes, error codes, and how to handle network and authentication failures.

The Veto SDK uses a structured error hierarchy so you can handle different failure modes precisely.

Error classes

VetoError

The base class for all Veto errors. All SDK errors extend this class.

class VetoError extends Error {
  code: string;       // machine-readable error code
  statusCode: number; // HTTP status code
  message: string;    // human-readable description
}

UnauthorizedError

Thrown when your API key is invalid or expired.

class UnauthorizedError extends VetoError {
  code = "UNAUTHORIZED";
  statusCode = 401;
}

RateLimitError

Thrown when you exceed the Veto API rate limit.

class RateLimitError extends VetoError {
  code = "RATE_LIMITED";
  statusCode = 429;
  retryAfterMs: number; // milliseconds to wait before retrying
}

---

Error codes

Code	Class	Description
UNAUTHORIZED	UnauthorizedError	Invalid or revoked API key
API_KEY_EXPIRED	UnauthorizedError	API key has passed its expiry date
INSUFFICIENT_SCOPE	VetoError	API key lacks the required scope (e.g., admin)
RATE_LIMITED	RateLimitError	API rate limit exceeded
TIMEOUT	VetoError	Request exceeded the configured timeout
NETWORK_ERROR	VetoError	Could not reach the Veto API
DENIED_BY_POLICY	VetoError	Authorization explicitly denied by a policy (thrown by vetoMiddleware)
AGENT_NOT_FOUND	VetoError	The agent ID does not exist in your workspace
AGENT_SUSPENDED	VetoError	The agent has been suspended and cannot be authorized
INTERNAL_ERROR	VetoError	An unexpected server error
UNKNOWN	VetoError	An error with no specific code (fallback)

---

Handling errors

import { VetoError, UnauthorizedError, RateLimitError } from "@useveto/node";

try {
  const result = await veto.authorize("agent-id", "tool-name");
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Retry after ${error.retryAfterMs}ms`);
  } else if (error instanceof UnauthorizedError) {
    console.log("Invalid API key — check VETO_API_KEY");
  } else if (error instanceof VetoError) {
    console.log(`${error.code}: ${error.message}`);
  }
}

authorize() does not throw when a tool is denied. A denial is a valid authorization outcome — it returns { allowed: false, reason: "..." }. Errors are only thrown for network failures, timeouts, and authentication problems.

---

Timeout behavior

The default request timeout is 5000ms. You can configure it when initializing the client:

const veto = new VetoClient({
  apiKey: process.env.VETO_API_KEY!,
  timeout: 3000, // 3 seconds
});

When a request times out, the SDK throws a VetoError with code: "TIMEOUT".

---

Fail-closed in MCP integrations

When you use createVetoGuard or vetoMiddleware, network errors and timeouts result in denials, not thrown exceptions. The MCP integration catches these errors and blocks the tool call rather than propagating the exception to the MCP server.

// Network error → tool call is blocked, no exception propagates
const protect = createVetoGuard(veto, { agentId: "support-bot" });
// onError defaults to "deny"

If you set onError: "allow", network failures will let the tool call proceed instead. See MCP Integration for details.