VB-OS Node.js SDK Error Handling

Error Hierarchy

All SDK errors extend VBOSError, which extends the native Error class.

Error Class	HTTP Status	Description
VBOSError	(base)	Base error with status, code, message, details, request ID
VBOSAuthenticationError	401	Invalid or missing API key
VBOSAuthorizationError	403	Insufficient permissions
VBOSNotFoundError	404	Resource not found
VBOSValidationError	400, 422	Invalid request data
VBOSRateLimitError	429	Rate limit exceeded
VBOSServerError	5xx	Server-side error

Base Error Fields

Every VBOSError instance exposes:

Field	Type	Description
statusCode	number	HTTP status code
errorCode	string	Machine-readable error code
message	string	Human-readable error message
details	object | null	Additional error context
requestId	string	Request ID for support reference

VBOSRateLimitError adds a retryAfter field (number | null) indicating seconds to wait before retrying.

Catching Errors

import {
  VBOSClient,
  VBOSError,
  VBOSNotFoundError,
  VBOSValidationError,
  VBOSRateLimitError,
} from '@vb-os/sdk';

const client = new VBOSClient({ apiKey: process.env.VBOS_API_KEY });

try {
  const result = await client.verify({
    project: 'my-project',
    workload: { applicant_age: 25 },
  });
} catch (err) {
  if (err instanceof VBOSNotFoundError) {
    console.error('Resource not found:', err.message);
  } else if (err instanceof VBOSValidationError) {
    console.error('Validation failed:', err.details);
  } else if (err instanceof VBOSRateLimitError) {
    console.error(`Rate limited. Retry after ${err.retryAfter}s`);
  } else if (err instanceof VBOSError) {
    console.error(`API error ${err.statusCode}:`, err.message);
    console.error('Request ID:', err.requestId);
  } else {
    throw err;
  }
}

Serialization

All errors support toJSON() for structured logging:

try {
  await client.projects.get('nonexistent');
} catch (err) {
  if (err instanceof VBOSError) {
    console.log(JSON.stringify(err.toJSON(), null, 2));
  }
}

Output:

{
  "name": "VBOSNotFoundError",
  "statusCode": 404,
  "errorCode": "not_found",
  "message": "Project not found",
  "requestId": "req_abc123",
  "details": null
}

Automatic Retries

The SDK automatically retries requests that fail with:

• 5xx status codes (server errors)
• Network errors (fetch failures, timeouts)

Retry behavior:

• Default: 3 retries (configurable via maxRetries)
• Backoff: exponential with jitter (random() * min(baseDelay * 2^attempt, maxDelay))
• Base delay: 1 second
• Max delay: 30 seconds

4xx errors are never retried (except rate limits are retried by the application, not the SDK). When a 429 response is received, the SDK throws VBOSRateLimitError with the retryAfter value from the response headers. Your application code should handle the wait.

const client = new VBOSClient({
  apiKey: process.env.VBOS_API_KEY,
  maxRetries: 5,     // increase retries
  timeout: 60,       // increase timeout (seconds)
});