Error Handling

SDKs

Python

Build robust Python applications with the Tabstack SDK's comprehensive exception hierarchy and handling patterns.

Building robust applications requires proper error handling. The Tabstack Python SDK provides specific exception classes for different error scenarios.

Error Class Hierarchy

TabstackError (base class)
├── APIError
│   ├── APIConnectionError
│   │   └── APITimeoutError
│   ├── APIResponseValidationError
│   └── APIStatusError
│       ├── BadRequestError (400)
│       ├── AuthenticationError (401)
│       ├── PermissionDeniedError (403)
│       ├── NotFoundError (404)
│       ├── ConflictError (409)
│       ├── UnprocessableEntityError (422)
│       ├── RateLimitError (429)
│       └── InternalServerError (>=500)

Importing Error Classes

import tabstack
from tabstack import (
    Tabstack,
    TabstackError,
    APIError,
    APIStatusError,
    APIConnectionError,
    APITimeoutError,
    APIResponseValidationError,
    BadRequestError,
    AuthenticationError,
    PermissionDeniedError,
    NotFoundError,
    ConflictError,
    UnprocessableEntityError,
    RateLimitError,
    InternalServerError,
)

Error Classes Reference

TabstackError

Base error class for all SDK errors.

APIError

Base class for all API-related errors.

APIConnectionError

Raised when the SDK cannot connect to the API.

Common causes:

Network connectivity issues
DNS resolution failures
Firewall blocking requests

APITimeoutError

A subclass of APIConnectionError raised when a request times out.

Common causes:

Server taking too long to respond
Network latency issues
Request timeout set too low

APIStatusError

Base class for HTTP status code errors. All status errors have these attributes:

status_code: int - HTTP status code
message: str - Error message
body: object - Response body

BadRequestError (400)

Raised when the request is malformed or invalid.

Common causes:

Missing required parameters
Invalid JSON schema format
Malformed request body

AuthenticationError (401)

Raised when authentication fails.

Common causes:

Invalid API key
Missing API key
Expired API key

PermissionDeniedError (403)

Raised when access to a resource is forbidden.

Common causes:

Insufficient permissions
Resource access denied

NotFoundError (404)

Raised when the requested resource is not found.

Common causes:

Invalid endpoint URL
Resource no longer exists

ConflictError (409)

Raised when there’s a conflict with the current state.

Common causes:

Resource already exists
Concurrent modification conflict

UnprocessableEntityError (422)

Raised when the request is valid but cannot be processed.

Common causes:

Invalid URL format
URL points to private/internal resources
Semantic validation errors

RateLimitError (429)

Raised when rate limits are exceeded.

Common causes:

Too many requests in a short period
API quota exceeded

InternalServerError (>=500)

Raised when the server encounters an internal error.

Common causes:

Failed to fetch the target URL
Page content too large
Failed to generate/extract data
Service temporarily unavailable (503)

Basic Error Handling

Simple Try-Except

import os
from tabstack import Tabstack, TabstackError

with Tabstack(api_key=os.getenv('TABSTACK_API_KEY')) as client:
    try:
        result = client.extract.markdown(url='https://example.com')
        print(result.content)
    except TabstackError as error:
        print(f'API error: {error}')
    except Exception as error:
        print(f'Unexpected error: {error}')

Handling Specific Error Types

import os
import tabstack
from tabstack import Tabstack

with Tabstack(api_key=os.getenv('TABSTACK_API_KEY')) as client:
    try:
        result = client.extract.markdown(url='https://example.com')
        print(result.content)
    except tabstack.AuthenticationError:
        print('Authentication failed. Please check your API key.')
    except tabstack.UnprocessableEntityError as error:
        print(f'Invalid or inaccessible URL: {error}')
    except tabstack.RateLimitError as error:
        print(f'Rate limited. Status: {error.status_code}')
    except tabstack.InternalServerError as error:
        print(f'Server error occurred: {error}')
    except tabstack.APIConnectionError as error:
        print(f'Connection error: {error.__cause__}')
    except tabstack.APIStatusError as error:
        print(f'API error {error.status_code}: {error.message}')
    except Exception as error:
        print(f'Unexpected error: {error}')
        raise

Advanced Error Handling

Retry Logic with Exponential Backoff

The SDK has built-in retry logic (default: 2 retries), but you can implement custom retry behavior:

import os
import time
import tabstack
from tabstack import Tabstack

def extract_with_retry(url: str, max_retries: int = 3, base_delay: float = 1.0):
    """Extract markdown with custom retry logic for server errors."""
    last_error = None

    for attempt in range(max_retries):
        try:
            with Tabstack(api_key=os.getenv('TABSTACK_API_KEY')) as client:
                result = client.extract.markdown(url=url)
                return result

        except (tabstack.InternalServerError, tabstack.RateLimitError) as error:
            last_error = error

            if attempt < max_retries - 1:
                # Exponential backoff: 1s, 2s, 4s, etc.
                delay = base_delay * (2 ** attempt)
                print(f"Attempt {attempt + 1} failed. Retrying in {delay}s...")
                time.sleep(delay)
                continue

        except tabstack.APIStatusError as error:
            # Don't retry client errors (4xx except 429)
            raise

    raise Exception(f"Failed after {max_retries} attempts: {last_error}")

# Usage
try:
    result = extract_with_retry('https://example.com')
    print('Success:', result.content[:100])
except Exception as error:
    print(f'Failed: {error}')

Batch Processing with Error Tracking

import os
from typing import List, Any
from dataclasses import dataclass
import tabstack
from tabstack import Tabstack

@dataclass
class BatchResult:
    url: str
    success: bool
    data: Any = None
    error: str = None

def batch_extract_with_error_handling(
    urls: List[str],
    schema: dict
) -> List[BatchResult]:
    """Extract from multiple URLs with error tracking."""
    results = []

    with Tabstack(api_key=os.getenv('TABSTACK_API_KEY')) as client:
        for url in urls:
            try:
                result = client.extract.json(url=url, json_schema=schema)
                results.append(BatchResult(
                    url=url,
                    success=True,
                    data=result
                ))
                print(f"Success: {url}")

            except tabstack.APIStatusError as error:
                results.append(BatchResult(
                    url=url,
                    success=False,
                    error=f"{error.status_code}: {error.message}"
                ))
                print(f"Failed: {url} - {error.status_code}: {error.message}")

            except Exception as error:
                results.append(BatchResult(
                    url=url,
                    success=False,
                    error=str(error)
                ))
                print(f"Failed: {url} - {error}")

    return results

# Usage
urls = [
    'https://example.com/page1',
    'https://example.com/page2',
    'https://example.com/page3'
]
schema = {"type": "object", "properties": {"title": {"type": "string"}}}

results = batch_extract_with_error_handling(urls, schema)

successful = [r for r in results if r.success]
failed = [r for r in results if not r.success]

print(f"\nBatch Complete: {len(successful)} succeeded, {len(failed)} failed")

if failed:
    print('\nFailed URLs:')
    for result in failed:
        print(f"  - {result.url}: {result.error}")

Error Logging

import os
import logging
import tabstack
from tabstack import Tabstack

# Configure logging
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
logger = logging.getLogger('tabstack_app')

def logged_extract(url: str):
    """Extract with comprehensive error logging."""
    with Tabstack(api_key=os.getenv('TABSTACK_API_KEY')) as client:
        try:
            logger.info(f"Starting extraction from {url}")
            result = client.extract.markdown(url=url)
            logger.info(f"Successfully extracted {len(result.content)} characters")
            return result

        except tabstack.APIStatusError as error:
            logger.error(
                f"API error during extraction",
                extra={
                    'url': url,
                    'error_type': type(error).__name__,
                    'status_code': error.status_code,
                    'message': str(error)
                }
            )
            raise

        except tabstack.APIConnectionError as error:
            logger.error(f"Connection error during extraction from {url}: {error}")
            raise

        except Exception as error:
            logger.exception(f"Unexpected error during extraction from {url}")
            raise

# Usage
logged_extract('https://example.com')

Automate Error Handling

The automate endpoint streams events, so error handling works differently:

import os
import tabstack
from tabstack import Tabstack

def automate_with_error_handling(task: str, url: str):
    """Execute automation with proper error handling."""
    with Tabstack(api_key=os.getenv('TABSTACK_API_KEY')) as client:
        try:
            stream = client.agent.automate(task=task, url=url)

            for event in stream:
                # Check event type for errors
                if event.event == 'error':
                    error_data = event.data
                    print(f'Automation error: {error_data}')
                    raise Exception(f'Automation failed: {error_data}')

                elif event.event == 'task:aborted':
                    reason = event.data
                    print(f'Task aborted: {reason}')
                    raise Exception(f'Task aborted: {reason}')

                elif event.event == 'complete':
                    result = event.data
                    print(f'Success: {result}')
                    return result

        except tabstack.APIStatusError as error:
            print(f'API error during automation: {error.status_code} - {error}')
            raise

        except tabstack.APIConnectionError as error:
            print(f'Connection error: {error}')
            raise

        except Exception as error:
            print(f'Unexpected error: {error}')
            raise

# Usage
automate_with_error_handling(
    'Extract the top 5 articles',
    'https://news.example.com'
)

Best Practices

1. Always Use Try-Except

# Good
try:
    result = client.extract.markdown(url=url)
except tabstack.TabstackError as error:
    # Handle error
    pass

2. Handle Specific Errors First

# Good: Specific to generic
try:
    result = client.extract.markdown(url=url)
except tabstack.AuthenticationError:
    # Handle auth error - don't retry
    pass
except tabstack.RateLimitError:
    # Handle rate limit - wait and retry
    pass
except tabstack.UnprocessableEntityError:
    # Handle invalid URL - check the URL
    pass
except tabstack.InternalServerError:
    # Handle server error - maybe retry
    pass
except tabstack.APIStatusError:
    # Handle other API errors
    pass
except tabstack.APIConnectionError:
    # Handle connection issues
    pass
except Exception:
    # Handle unexpected errors
    pass

3. Implement Retry for Transient Errors

# Good: Retry server errors and rate limits
try:
    result = client.extract.markdown(url=url)
except (tabstack.InternalServerError, tabstack.RateLimitError):
    # Retry with backoff
    pass
except tabstack.AuthenticationError:
    # Don't retry - fix the API key
    raise

4. Use Context Managers

# Good: Automatic cleanup even on errors
with Tabstack(api_key=api_key) as client:
    result = client.extract.markdown(url=url)

5. Configure Retries at Client Level

# Disable retries for faster failure
client = Tabstack(max_retries=0)

# Increase retries for important requests
client = Tabstack(max_retries=5)

# Per-request retry override
result = client.with_options(max_retries=5).extract.markdown(url=url)

Common Error Scenarios

Invalid API Key

import tabstack
from tabstack import Tabstack

try:
    with Tabstack(api_key='invalid-key') as client:
        result = client.extract.markdown(url='https://example.com')
except tabstack.AuthenticationError:
    print('Please set a valid API key in TABSTACK_API_KEY environment variable')

URL Cannot Be Accessed

import tabstack

try:
    result = client.extract.markdown(url='https://localhost:3000')
except tabstack.UnprocessableEntityError:
    print('Cannot access private URLs like localhost')

Request Timeout

import tabstack
from tabstack import Tabstack

try:
    # Set a short timeout
    with Tabstack(timeout=5.0) as client:
        result = client.extract.markdown(url='https://slow-site.example.com')
except tabstack.APITimeoutError:
    print('Request timed out - try increasing the timeout')

Rate Limiting

import tabstack
import time

try:
    result = client.extract.markdown(url='https://example.com')
except tabstack.RateLimitError as error:
    print(f'Rate limited (status {error.status_code}). Waiting before retry...')
    time.sleep(60)  # Wait before retrying

Next Steps

Quickstart: Get started with the SDK
Generate Features: Discover AI transformations
Automate Features: Execute browser automation