Error Handling

SDK Error Handling

SDKs provide language-native error handling that follows each language's conventions. All errors include consistent information to help you handle them programmatically.

Go

// Errors implement the standard Go error interface
response, err := client.Files.Upload(ctx, uploadRequest)
if err != nil {
    // Handle the error
    log.Printf("Error: %v", err)

    // Check specific error types using helper functions
    if silentwitness.IsAuthenticationError(err) {
        // Handle authentication error
    } else if silentwitness.IsRateLimitError(err) {
        // Handle rate limit error
    }
}

TypeScript

try {
    const response = await client.files.upload(uploadParams);
    // Handle success
} catch (error) {
    // Handle the error
    console.error('Error:', error.message);

    // Check specific error types
    if (isAuthenticationError(error)) {
        // Handle authentication error
    } else if (isRateLimitError(error)) {
        // Handle rate limit error
    }
}

Error Types

SDKs classify errors into well-defined categories for consistent handling across languages:

Error Type	Description	Example
Authentication Error	Invalid or missing API key	AuthenticationError
Validation Error	Request parameters are invalid or missing	ValidationError
Permission Error	Insufficient permissions for this operation	PermissionError
Rate Limit Error	API rate limit exceeded	RateLimitError
Not Found Error	Requested resource does not exist	NotFoundError
Server Error	Unexpected server error	ServerError
Network Error	Network connectivity issues	NetworkError

Common Error Scenarios

Authentication Error

Go

response, err := client.Files.Upload(ctx, uploadRequest)
if err != nil {
    if silentwitness.IsAuthenticationError(err) {
        log.Printf("Invalid API key: %v", err)
        // Check API key configuration
    }
}

TypeScript

try {
    const response = await client.files.upload(uploadParams);
} catch (error) {
    if (isAuthenticationError(error)) {
        console.error("Invalid API key:", error.message);
        // Check API key configuration
    }
}

What causes this error:

• Missing API key in SDK configuration
• Invalid API key format
• Expired or revoked API key

How to fix:

1. Verify your API key is correctly set in SDK configuration
2. Ensure the API key starts with sk- and is 64 characters long
3. Check if the API key is still active in your dashboard

Validation Error

Go

response, err := client.Calculations.StartDeltaV(ctx, &silentwitness.StartDeltaVRequest{
    VehicleFiles: []string{}, // Empty - will cause validation error
})
if err != nil {
    if silentwitness.IsValidationError(err) {
        log.Printf("Invalid request: %v", err)
        // Check required parameters
    }
}

TypeScript

try {
    const response = await client.calculations.startDeltaV({
        vehicleFiles: [], // Empty - will cause validation error
    });
} catch (error) {
    if (isValidationError(error)) {
        console.error("Invalid request:", error.message);
        // Check required parameters
    }
}

What causes this error:

• Missing required parameters
• Invalid parameter values or types
• Files that don't exist or can't be accessed

How to fix:

1. Review the error message for specific validation failures
2. Ensure all required parameters are provided
3. Verify file IDs exist and are accessible

Rate Limit Error

Go

response, err := client.Files.Upload(ctx, uploadRequest)
if err != nil {
    if silentwitness.IsRateLimitError(err) {
        // This should rarely happen due to automatic retries
        log.Printf("Rate limit exceeded after retries: %v", err)
    }
}

TypeScript

try {
    const response = await client.files.upload(uploadParams);
} catch (error) {
    if (isRateLimitError(error)) {
        // This should rarely happen due to automatic retries
        console.error("Rate limit exceeded after retries:", error.message);
    }
}

What causes this error:

• Making too many requests within the rate limit window
• Concurrent requests exceeding allowed limits

How to fix:

1. Usually automatic: SDKs handle rate limiting with exponential backoff
2. Reduce concurrency: Limit parallel requests in your application
3. Contact support: Request higher rate limits if needed

Server Error

Go

response, err := client.Calculations.GetStatus(ctx, statusRequest)
if err != nil {
    if silentwitness.IsServerError(err) {
        // SDK automatically retries server errors
        log.Printf("Server error (retried automatically): %v", err)
    }
}

TypeScript

try {
    const response = await client.calculations.getStatus(statusParams);
} catch (error) {
    if (isServerError(error)) {
        // SDK automatically retries server errors
        console.error("Server error (retried automatically):", error.message);
    }
}

What causes this error:

• Temporary server issues or maintenance
• Service overload or degraded performance

What to do:

1. SDK Handles Retries: SDKs automatically retry server errors
2. Report Persistent Issues: Contact support if errors persist
3. Check Status: Monitor our status page for known issues

Error Helper Functions

Go SDK

import "github.com/silentwitness/go-sdk"

// Check specific error types
if silentwitness.IsAuthenticationError(err) {
    // Handle authentication error
}
if silentwitness.IsRateLimitError(err) {
    // Handle rate limit error
}
if silentwitness.IsValidationError(err) {
    // Handle validation error
}
if silentwitness.IsNetworkError(err) {
    // Handle network error
}
if silentwitness.IsServerError(err) {
    // Handle server error
}

TypeScript SDK

import {
  isAuthenticationError,
  isRateLimitError,
  isValidationError,
  isNetworkError,
  isServerError
} from "@silentwitness/typescript-sdk";

// Check specific error types
if (isAuthenticationError(error)) {
    // Handle authentication error
}
if (isRateLimitError(error)) {
    // Handle rate limit error
}
if (isValidationError(error)) {
    // Handle validation error
}
if (isNetworkError(error)) {
    // Handle network error
}
if (isServerError(error)) {
    // Handle server error
}

Automatic Error Recovery

Built-in Retry Logic

SDKs automatically handle transient errors:

⏰

Rate Limiting

Exponential backoff when rate limits are exceeded

server

Server Errors

Automatic retries for temporary server issues

wifi

Network Issues

Retry logic for network connectivity problems

Retry Configuration

Go

client := silentwitness.NewClient(silentwitness.Config{
    APIKey:  "sk-your-api-key",
    Retries: 5,                    // Number of retry attempts
    Timeout: 60 * time.Second,     // Total timeout including retries
})

TypeScript

const client = new SilentWitnessClient({
    apiKey: "sk-your-api-key",
    retries: 5,              // Number of retry attempts
    timeout: 60000,          // Total timeout including retries (ms)
});

Troubleshooting Guide

Getting authentication errors with valid API key

Possible causes:

• API key not properly configured in SDK
• Environment variable not set
• API key copied incorrectly

Solutions:

1. Verify API key format (should start with sk- and be 64 characters)
2. Check environment variable is set correctly
3. Ensure no extra spaces or characters in the key
4. Test with a fresh API key from the dashboard

Intermittent server errors

Possible causes:

• Temporary service issues
• Network connectivity problems
• High load on services

Solutions:

• SDKs automatically retry server errors with exponential backoff
• Check our status page for known issues
• Monitor error patterns to identify systematic issues
• Contact support if errors persist

Rate limit errors but usage seems low

Possible causes:

• Burst of concurrent requests
• Multiple applications using same API key
• Previous high usage affecting current window

Solutions:

1. Implement request queuing in your application
2. Use separate API keys for different applications
3. Contact support for higher rate limits if needed
4. Monitor request patterns in your dashboard

Network connectivity issues

Possible causes:

• Firewall blocking connections
• DNS resolution problems
• Proxy configuration issues

Solutions:

1. Verify network connectivity to core.silentwitness.ai
2. Check firewall rules for HTTPS traffic
3. Test DNS resolution for the API domain
4. Configure proxy settings if needed

File upload failures

Possible causes:

• File too large for processing
• Unsupported file format
• Corrupted file data

Solutions:

1. Check file size limits in documentation
2. Verify file format is supported (JPEG, PNG, PDF, etc.)
3. Test with a different file to isolate the issue
4. Ensure file is not corrupted or empty

Best Practices

Error Handling Strategy

1. Let SDKs Handle Retries: Trust the built-in retry logic for transient errors
2. Handle Business Logic Errors: Focus on authentication, validation, and permission errors
3. Log Comprehensively: Log errors with context for debugging
4. Graceful Degradation: Provide fallback behavior when possible

Example: Robust Error Handling

Go

func uploadFileWithRetry(client *silentwitness.Client, filePath string) error {
    fileData, err := os.ReadFile(filePath)
    if err != nil {
        return fmt.Errorf("failed to read file: %w", err)
    }

    response, err := client.Files.Upload(ctx, &silentwitness.UploadFileRequest{
        Content:  fileData,
        Filename: silentwitness.String(filepath.Base(filePath)),
        Purpose:  silentwitness.String("crash_analysis"),
    })

    if err != nil {
        // Log the error for debugging
        log.Printf("Upload failed for %s: %v", filePath, err)

        if silentwitness.IsAuthenticationError(err) {
            return fmt.Errorf("authentication failed - check API key: %w", err)
        } else if silentwitness.IsValidationError(err) {
            return fmt.Errorf("invalid file or parameters: %w", err)
        }
        // Other errors (rate limit, server, network) are handled by SDK retries
        return fmt.Errorf("upload failed after retries: %w", err)
    }

    log.Printf("File uploaded successfully: %s", response.FileId)
    return nil
}

TypeScript

async function uploadFileWithRetry(
    client: SilentWitnessClient,
    fileData: Buffer,
    filename: string
): Promise<string> {
    try {
        const response = await client.files.upload({
            content: fileData,
            filename: filename,
            purpose: "crash_analysis_plaintiff"
        });

        console.log(`File uploaded successfully: ${response.fileId}`);
        return response.fileId;

    } catch (error) {
        // Log the error for debugging
        console.error(`Upload failed for ${filename}:`, error);

        if (isAuthenticationError(error)) {
            throw new Error(`Authentication failed - check API key: ${error.message}`);
        } else if (isValidationError(error)) {
            throw new Error(`Invalid file or parameters: ${error.message}`);
        }
        // Other errors (rate limit, server, network) are handled by SDK retries
        throw new Error(`Upload failed after retries: ${error.message}`);
    }
}