Error Handling

Sentinel throws typed errors you can catch and handle. Audit failures are never fatal — they are caught and logged internally.

Error Types

SentinelError

Base class for all Sentinel errors. Has a code property.

SentinelBudgetError

Thrown when a payment would exceed a budget limit. Contains a violation object with type, limit, current spend, and attempted amount.

import { wrapWithSentinel, SentinelBudgetError } from "@valeo/x402";

try {
  const res = await secureFetch(url);
  return await res.json();
} catch (err) {
  if (err instanceof SentinelBudgetError) {
    console.error("Budget limit hit:", err.violation.type, err.violation.limit);
    // Fallback: retry later, notify user, use cached data
  }
  throw err;
}

SentinelAuditError

Thrown when audit logging fails (e.g., storage write error). Never blocks the request — the payment already succeeded. Contains optional record for debugging.

import { AuditLogger, SentinelAuditError } from "@valeo/x402";

try {
  await logger.log(record);
} catch (err) {
  if (err instanceof SentinelAuditError) {
    console.error("Audit failed (payment succeeded):", err.message);
  }
}

SentinelConfigError

Thrown at wrap time when config is invalid (empty agentId, invalid USDC amounts, etc.). Use validateConfig to check before wrapping.

import { wrapWithSentinel, validateConfig, SentinelConfigError } from "@valeo/x402";

const config = { agentId: "agent-1", budget: standardPolicy() };
validateConfig(config);  // throws SentinelConfigError if invalid
const secureFetch = wrapWithSentinel(fetchWithPayment, config);