Error Handling

SDKs

TypeScript

Build robust TypeScript applications with the Tabstack SDK's comprehensive error class hierarchy and handling patterns.

Building robust applications requires proper error handling. The Tabstack SDK provides a comprehensive error class hierarchy and patterns for handling different error scenarios.

Error Class Hierarchy

The SDK includes specific error classes for different failure scenarios:

TabstackError (base class)
├── APIError (with status code)
│   ├── AuthenticationError (401)
│   ├── PermissionDeniedError (403)
│   ├── NotFoundError (404)
│   ├── ConflictError (409)
│   ├── UnprocessableEntityError (422)
│   ├── RateLimitError (429)
│   ├── InternalServerError (500+)
│   └── BadRequestError (400)
├── APIConnectionError
└── APIConnectionTimeoutError

import Tabstack, {
  TabstackError,
  APIError,
  AuthenticationError,
  PermissionDeniedError,
  NotFoundError,
  ConflictError,
  UnprocessableEntityError,
  RateLimitError,
  InternalServerError,
  BadRequestError,
  APIConnectionError,
  APIConnectionTimeoutError
} from '@tabstack/sdk';

const Tabstack = require('@tabstack/sdk').default;
const {
  TabstackError,
  APIError,
  AuthenticationError,
  PermissionDeniedError,
  NotFoundError,
  ConflictError,
  UnprocessableEntityError,
  RateLimitError,
  InternalServerError,
  BadRequestError,
  APIConnectionError,
  APIConnectionTimeoutError
} = require('@tabstack/sdk');

Error Classes Reference

TabstackError

Base error class for all SDK errors. All other error classes extend this.

Properties:

message: string - Error message
name: string - Error class name
cause?: Error - Optional underlying error

APIError

Generic API error with HTTP status code. Used for errors that don’t match specific error classes.

Properties:

status: number - HTTP status code
message: string - Error message

AuthenticationError (401)

Thrown when authentication fails.

Common causes:

Invalid API key
Missing API key
Expired API key

PermissionDeniedError (403)

Thrown when you don’t have permission to access a resource.

Common causes:

Insufficient permissions
Resource access denied

NotFoundError (404)

Thrown when a requested resource is not found.

Common causes:

Invalid endpoint
Resource doesn’t exist

ConflictError (409)

Thrown when there’s a conflict with the current state of a resource.

Common causes:

Duplicate resource creation
Version conflicts

UnprocessableEntityError (422)

Thrown when the provided data is invalid or inaccessible.

Common causes:

Malformed URL format
URL points to private/internal resources (localhost, 127.0.0.1, private IPs)
URL is unreachable
Invalid JSON schema format

RateLimitError (429)

Thrown when you’ve exceeded the rate limit.

Common causes:

Too many requests in a short period
Quota exceeded

InternalServerError (500+)

Thrown when the server encounters an internal error.

Common causes:

Failed to fetch the URL
Page content too large
Failed to generate/extract data
Server-side processing error

BadRequestError (400)

Thrown when the request is malformed or invalid.

Common causes:

Missing required parameters
Invalid JSON schema format
Malformed request body

APIConnectionError

Thrown when the SDK cannot connect to the API.

Common causes:

Network connectivity issues
DNS resolution failures
Firewall blocking requests

APIConnectionTimeoutError

Thrown when the connection times out.

Common causes:

Slow network connection
Server not responding
Request took too long

Basic Error Handling

Simple Try-Catch

TypeScript
JavaScript

import Tabstack, { TabstackError } from '@tabstack/sdk';

const client = new Tabstack({
  apiKey: process.env.TABSTACK_API_KEY!
});

try {
  const result = await client.extract.markdown({ url: 'https://example.com' });
  console.log(result.content);
} catch (error) {
  if (error instanceof TabstackError) {
    console.error('API error:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

const Tabstack = require('@tabstack/sdk').default;
const { TabstackError } = require('@tabstack/sdk');

const client = new Tabstack({
  apiKey: process.env.TABSTACK_API_KEY
});

try {
  const result = await client.extract.markdown({ url: 'https://example.com' });
  console.log(result.content);
} catch (error) {
  if (error instanceof TabstackError) {
    console.error('API error:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

Handling Specific Error Types

TypeScript
JavaScript

import Tabstack, {
  AuthenticationError,
  UnprocessableEntityError,
  InternalServerError,
  RateLimitError,
  TabstackError
} from '@tabstack/sdk';

const client = new Tabstack({
  apiKey: process.env.TABSTACK_API_KEY!
});

async function extractWithErrorHandling(url: string) {
  try {
    const result = await client.extract.markdown({ url });
    return result;
  } catch (error) {
    if (error instanceof AuthenticationError) {
      console.error('Authentication failed. Please check your API key.');
    } else if (error instanceof UnprocessableEntityError) {
      console.error(`Invalid or inaccessible URL: ${url}`);
    } else if (error instanceof RateLimitError) {
      console.error('Rate limit exceeded. Waiting before retry...');
      await new Promise(resolve => setTimeout(resolve, 60000));
      return extractWithErrorHandling(url);
    } else if (error instanceof InternalServerError) {
      console.error('Server error occurred. Retrying in 5 seconds...');
      await new Promise(resolve => setTimeout(resolve, 5000));
      return extractWithErrorHandling(url);
    } else if (error instanceof TabstackError) {
      console.error('API error:', error.message);
    } else {
      console.error('Unexpected error:', error);
      throw error;
    }
  }
}

const Tabstack = require('@tabstack/sdk').default;
const {
  AuthenticationError,
  UnprocessableEntityError,
  InternalServerError,
  RateLimitError,
  TabstackError
} = require('@tabstack/sdk');

const client = new Tabstack({
  apiKey: process.env.TABSTACK_API_KEY
});

async function extractWithErrorHandling(url) {
  try {
    const result = await client.extract.markdown({ url });
    return result;
  } catch (error) {
    if (error instanceof AuthenticationError) {
      console.error('Authentication failed. Please check your API key.');
    } else if (error instanceof UnprocessableEntityError) {
      console.error(`Invalid or inaccessible URL: ${url}`);
    } else if (error instanceof RateLimitError) {
      console.error('Rate limit exceeded. Waiting before retry...');
      await new Promise(resolve => setTimeout(resolve, 60000));
      return extractWithErrorHandling(url);
    } else if (error instanceof InternalServerError) {
      console.error('Server error occurred. Retrying in 5 seconds...');
      await new Promise(resolve => setTimeout(resolve, 5000));
      return extractWithErrorHandling(url);
    } else if (error instanceof TabstackError) {
      console.error('API error:', error.message);
    } else {
      console.error('Unexpected error:', error);
      throw error;
    }
  }
}

Advanced Error Handling Patterns

Retry Logic with Exponential Backoff

TypeScript
JavaScript

import Tabstack, { InternalServerError, RateLimitError } from '@tabstack/sdk';

async function extractWithRetry(
  client: Tabstack,
  url: string,
  maxRetries: number = 3,
  baseDelay: number = 1000
) {
  let lastError: Error;

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const result = await client.extract.markdown({ url });
      return result;
    } catch (error) {
      lastError = error;

      if (error instanceof InternalServerError || error instanceof RateLimitError) {
        if (attempt < maxRetries - 1) {
          const delay = baseDelay * Math.pow(2, attempt);
          console.log(`Attempt ${attempt + 1} failed. Retrying in ${delay}ms...`);
          await new Promise(resolve => setTimeout(resolve, delay));
          continue;
        }
      }

      throw error;
    }
  }

  throw new Error(`Failed after ${maxRetries} attempts: ${lastError.message}`);
}

// Usage
const client = new Tabstack({ apiKey: process.env.TABSTACK_API_KEY! });

try {
  const result = await extractWithRetry(client, 'https://example.com');
  console.log('Success:', result.content);
} catch (error) {
  console.error('Failed:', error.message);
}

const Tabstack = require('@tabstack/sdk').default;
const { InternalServerError, RateLimitError } = require('@tabstack/sdk');

async function extractWithRetry(
  client,
  url,
  maxRetries = 3,
  baseDelay = 1000
) {
  let lastError;

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const result = await client.extract.markdown({ url });
      return result;
    } catch (error) {
      lastError = error;

      if (error instanceof InternalServerError || error instanceof RateLimitError) {
        if (attempt < maxRetries - 1) {
          const delay = baseDelay * Math.pow(2, attempt);
          console.log(`Attempt ${attempt + 1} failed. Retrying in ${delay}ms...`);
          await new Promise(resolve => setTimeout(resolve, delay));
          continue;
        }
      }

      throw error;
    }
  }

  throw new Error(`Failed after ${maxRetries} attempts: ${lastError.message}`);
}

// Usage
const client = new Tabstack({ apiKey: process.env.TABSTACK_API_KEY });

try {
  const result = await extractWithRetry(client, 'https://example.com');
  console.log('Success:', result.content);
} catch (error) {
  console.error('Failed:', error.message);
}

Batch Processing with Error Tracking

TypeScript
JavaScript

import Tabstack, { TabstackError } from '@tabstack/sdk';

interface BatchResult<T> {
  url: string;
  success: boolean;
  data?: T;
  error?: string;
}

async function batchExtractWithErrorHandling<T>(
  client: Tabstack,
  urls: string[],
  schema: object
): Promise<BatchResult<T>[]> {
  const results: BatchResult<T>[] = [];

  for (const url of urls) {
    try {
      const result = await client.extract.json({ url, json_schema: schema });
      results.push({
        url,
        success: true,
        data: result as T
      });
      console.log(`Success: ${url}`);
    } catch (error) {
      const errorMessage = error instanceof TabstackError
        ? error.message
        : 'Unknown error';

      results.push({
        url,
        success: false,
        error: errorMessage
      });
      console.error(`Failed: ${url} - ${errorMessage}`);
    }

    // Respectful delay between requests
    await new Promise(resolve => setTimeout(resolve, 500));
  }

  return results;
}

// Usage
const client = new Tabstack({ apiKey: process.env.TABSTACK_API_KEY! });
const urls = [
  'https://example.com/page1',
  'https://example.com/page2',
  'https://example.com/page3'
];

const schema = {
  type: 'object',
  properties: {
    title: { type: 'string' }
  }
};

const results = await batchExtractWithErrorHandling(client, urls, schema);

const successful = results.filter(r => r.success);
const failed = results.filter(r => !r.success);

console.log(`\nBatch Complete: ${successful.length} succeeded, ${failed.length} failed`);

if (failed.length > 0) {
  console.log('\nFailed URLs:');
  failed.forEach(r => console.log(`  - ${r.url}: ${r.error}`));
}

const Tabstack = require('@tabstack/sdk').default;
const { TabstackError } = require('@tabstack/sdk');

async function batchExtractWithErrorHandling(client, urls, schema) {
  const results = [];

  for (const url of urls) {
    try {
      const result = await client.extract.json({ url, json_schema: schema });
      results.push({
        url,
        success: true,
        data: result
      });
      console.log(`Success: ${url}`);
    } catch (error) {
      const errorMessage = error instanceof TabstackError
        ? error.message
        : 'Unknown error';

      results.push({
        url,
        success: false,
        error: errorMessage
      });
      console.error(`Failed: ${url} - ${errorMessage}`);
    }

    // Respectful delay between requests
    await new Promise(resolve => setTimeout(resolve, 500));
  }

  return results;
}

// Usage
const client = new Tabstack({ apiKey: process.env.TABSTACK_API_KEY });
const urls = [
  'https://example.com/page1',
  'https://example.com/page2',
  'https://example.com/page3'
];

const schema = {
  type: 'object',
  properties: {
    title: { type: 'string' }
  }
};

const results = await batchExtractWithErrorHandling(client, urls, schema);

const successful = results.filter(r => r.success);
const failed = results.filter(r => !r.success);

console.log(`\nBatch Complete: ${successful.length} succeeded, ${failed.length} failed`);

if (failed.length > 0) {
  console.log('\nFailed URLs:');
  failed.forEach(r => console.log(`  - ${r.url}: ${r.error}`));
}

Error Logging and Monitoring

TypeScript
JavaScript

import Tabstack, { TabstackError, APIError } from '@tabstack/sdk';

interface ErrorLog {
  timestamp: Date;
  operation: string;
  url?: string;
  errorType: string;
  message: string;
  status?: number;
  stack?: string;
}

class ErrorTracker {
  private errors: ErrorLog[] = [];

  log(operation: string, error: Error, url?: string) {
    const errorLog: ErrorLog = {
      timestamp: new Date(),
      operation,
      url,
      errorType: error.constructor.name,
      message: error.message,
      stack: error.stack
    };

    if (error instanceof APIError) {
      errorLog.status = error.status;
    }

    this.errors.push(errorLog);
    console.error(`[${errorLog.timestamp.toISOString()}] ${operation} failed:`, error.message);
  }

  getErrors() {
    return this.errors;
  }

  getSummary() {
    const byType = this.errors.reduce((acc, error) => {
      acc[error.errorType] = (acc[error.errorType] || 0) + 1;
      return acc;
    }, {} as Record<string, number>);

    return {
      total: this.errors.length,
      byType
    };
  }

  exportToJSON() {
    return JSON.stringify(this.errors, null, 2);
  }
}

// Usage
const client = new Tabstack({ apiKey: process.env.TABSTACK_API_KEY! });
const errorTracker = new ErrorTracker();

async function monitoredExtract(url: string) {
  try {
    return await client.extract.markdown({ url });
  } catch (error) {
    errorTracker.log('extract.markdown', error, url);
    throw error;
  }
}

const urls = ['https://example.com/page1', 'https://example.com/page2'];

for (const url of urls) {
  try {
    await monitoredExtract(url);
  } catch (error) {
    // Error already logged, continue processing
  }
}

console.log('\nError Summary:', errorTracker.getSummary());

const Tabstack = require('@tabstack/sdk').default;
const { APIError } = require('@tabstack/sdk');

class ErrorTracker {
  constructor() {
    this.errors = [];
  }

  log(operation, error, url) {
    const errorLog = {
      timestamp: new Date(),
      operation,
      url,
      errorType: error.constructor.name,
      message: error.message,
      stack: error.stack
    };

    if (error instanceof APIError) {
      errorLog.status = error.status;
    }

    this.errors.push(errorLog);
    console.error(`[${errorLog.timestamp.toISOString()}] ${operation} failed:`, error.message);
  }

  getErrors() {
    return this.errors;
  }

  getSummary() {
    const byType = this.errors.reduce((acc, error) => {
      acc[error.errorType] = (acc[error.errorType] || 0) + 1;
      return acc;
    }, {});

    return {
      total: this.errors.length,
      byType
    };
  }

  exportToJSON() {
    return JSON.stringify(this.errors, null, 2);
  }
}

// Usage
const client = new Tabstack({ apiKey: process.env.TABSTACK_API_KEY });
const errorTracker = new ErrorTracker();

async function monitoredExtract(url) {
  try {
    return await client.extract.markdown({ url });
  } catch (error) {
    errorTracker.log('extract.markdown', error, url);
    throw error;
  }
}

const urls = ['https://example.com/page1', 'https://example.com/page2'];

for (const url of urls) {
  try {
    await monitoredExtract(url);
  } catch (error) {
    // Error already logged, continue processing
  }
}

console.log('\nError Summary:', errorTracker.getSummary());

Automate Error Handling

Automate operations stream events and require different error handling:

TypeScript
JavaScript

import Tabstack, { TabstackError } from '@tabstack/sdk';

const client = new Tabstack({ apiKey: process.env.TABSTACK_API_KEY! });

async function automateWithErrorHandling(task: string, url: string) {
  try {
    const stream = await client.agent.automate({
      task,
      url,
      guardrails: 'browse and extract only'
    });

    for await (const event of stream) {
      if (event.event === 'error') {
        const error = event.data?.error;
        console.error('Automation error:', error);
        throw new Error(`Automation failed: ${error}`);
      }

      if (event.event === 'task:aborted') {
        const reason = event.data?.reason;
        console.warn('Task aborted:', reason);
        throw new Error(`Task aborted: ${reason}`);
      }

      if (event.event === 'task:validation_error') {
        const error = event.data?.error;
        console.error('Validation failed:', error);
      }

      if (event.event === 'task:completed') {
        const result = event.data?.finalAnswer;
        console.log('Success:', result);
        return result;
      }
    }
  } catch (error) {
    if (error instanceof TabstackError) {
      console.error('API error during automation:', error.message);
    } else {
      console.error('Unexpected error:', error);
    }
    throw error;
  }
}

// Usage
try {
  await automateWithErrorHandling(
    'Extract the top 5 articles',
    'https://news.example.com'
  );
} catch (error) {
  console.error('Automation failed completely:', error.message);
}

const Tabstack = require('@tabstack/sdk').default;
const { TabstackError } = require('@tabstack/sdk');

const client = new Tabstack({ apiKey: process.env.TABSTACK_API_KEY });

async function automateWithErrorHandling(task, url) {
  try {
    const stream = await client.agent.automate({
      task,
      url,
      guardrails: 'browse and extract only'
    });

    for await (const event of stream) {
      if (event.event === 'error') {
        const error = event.data?.error;
        console.error('Automation error:', error);
        throw new Error(`Automation failed: ${error}`);
      }

      if (event.event === 'task:aborted') {
        const reason = event.data?.reason;
        console.warn('Task aborted:', reason);
        throw new Error(`Task aborted: ${reason}`);
      }

      if (event.event === 'task:validation_error') {
        const error = event.data?.error;
        console.error('Validation failed:', error);
      }

      if (event.event === 'task:completed') {
        const result = event.data?.finalAnswer;
        console.log('Success:', result);
        return result;
      }
    }
  } catch (error) {
    if (error instanceof TabstackError) {
      console.error('API error during automation:', error.message);
    } else {
      console.error('Unexpected error:', error);
    }
    throw error;
  }
}

// Usage
try {
  await automateWithErrorHandling(
    'Extract the top 5 articles',
    'https://news.example.com'
  );
} catch (error) {
  console.error('Automation failed completely:', error.message);
}

Best Practices

1. Always Use Try-Catch

// Bad: No error handling
const result = await client.extract.markdown({ url });

// Good: Proper error handling
try {
  const result = await client.extract.markdown({ url });
} catch (error) {
  // Handle error
}

2. Handle Specific Errors First

try {
  // API call
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Handle auth error
  } else if (error instanceof UnprocessableEntityError) {
    // Handle URL error
  } else if (error instanceof TabstackError) {
    // Handle other API errors
  } else {
    // Handle unexpected errors
  }
}

3. Implement Retry Logic for Transient Errors

if (error instanceof InternalServerError || error instanceof RateLimitError) {
  // Implement retry with backoff
} else if (error instanceof AuthenticationError || error instanceof BadRequestError) {
  // Don't retry - fix the issue first
  throw error;
}

4. Log Errors for Debugging

try {
  const result = await client.extract.json({ url, json_schema: schema });
} catch (error) {
  console.error(`Failed to extract from ${url}:`, {
    errorType: error.constructor.name,
    message: error.message,
    url,
    timestamp: new Date().toISOString()
  });
}

5. Provide User-Friendly Messages

try {
  const result = await client.extract.markdown({ url });
} catch (error) {
  if (error instanceof AuthenticationError) {
    return 'Your API key is invalid. Please check your credentials and try again.';
  } else if (error instanceof UnprocessableEntityError) {
    return 'The URL you provided cannot be accessed. Please verify it is correct and publicly accessible.';
  } else {
    return 'An unexpected error occurred. Please try again later or contact support.';
  }
}

6. Clean Up Resources on Error

let logFile;
try {
  logFile = openLog();
  const result = await client.extract.markdown({ url });
  writeLog(logFile, result);
} catch (error) {
  console.error('Error:', error);
  throw error;
} finally {
  if (logFile) {
    closeLog(logFile);
  }
}

Common Error Scenarios

Invalid API Key

try {
  const result = await client.extract.markdown({ url });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Please set a valid API key in TABSTACK_API_KEY environment variable');
    process.exit(1);
  }
}

URL Cannot Be Accessed

try {
  const result = await client.extract.markdown({ url: 'https://localhost:3000' });
} catch (error) {
  if (error instanceof UnprocessableEntityError) {
    console.error('Cannot access private URLs like localhost');
  }
}

Schema Mismatch

try {
  const result = await client.extract.json({ url, json_schema: incompatibleSchema });
} catch (error) {
  if (error instanceof InternalServerError && error.message.includes('failed to generate')) {
    console.error('Schema does not match page content. Try generating a schema first.');
  }
}

Next Steps

Quickstart: Get started with the SDK
Generate Features: Discover AI-powered transformations
Automate Features: Execute browser automation
REST API Documentation: View REST API error responses