Error Handling

The Scribeberry SDK throws typed errors that you can catch and handle specifically. All errors extend the base ScribeberryError class.

Error Classes

import {
  ScribeberryError,     // Base error — all SDK errors extend this
  AuthenticationError,  // 401 — invalid or expired key/token
  RateLimitError,       // 429 — too many requests
} from '@scribeberry/sdk';

`ScribeberryError`

The base class for all SDK errors. Contains a machine-readable code and optional HTTP status.

try {
  await sb.templates.list();
} catch (error) {
  if (error instanceof ScribeberryError) {
    console.error(`[${error.code}] ${error.message}`);
    console.error(`HTTP Status: ${error.status}`);
  }
}

`AuthenticationError`

Thrown when the API key or token is invalid, expired, or missing.

try {
  await sb.templates.list();
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Prompt user to re-authenticate or check API key
    console.error('Invalid API key. Check your configuration.');
  }
}

`RateLimitError`

Thrown when you exceed the rate limit for your project.

try {
  await sb.templates.list();
} catch (error) {
  if (error instanceof RateLimitError) {
    // Back off and retry after a delay
    await new Promise((r) => setTimeout(r, 5000));
    return sb.templates.list(); // retry
  }
}

Error Codes

REST API Errors

Code	Status	Description
`AUTHENTICATION_ERROR`	401	Invalid or expired API key
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`MISSING_API_KEY`	—	No API key provided
`INVALID_API_KEY_FORMAT`	—	Key doesn't match expected prefix
`INVALID_TOKEN_SCOPE`	—	Temp token used for REST call
`TIMEOUT`	408	Request timed out
`NETWORK_ERROR`	—	Network connectivity issue
`HTTP_400`	400	Bad request (check parameters)
`HTTP_404`	404	Resource not found
`HTTP_500`	500	Server error

Realtime/WebSocket Errors

Code	Description
`CONNECTION_ERROR`	Failed to establish WebSocket connection
`CONNECTION_CLOSED`	WebSocket closed unexpectedly
`CONNECT_TIMEOUT`	Server didn't acknowledge session within 10s
`SESSION_STATE_ERROR`	Operation invalid for current session state
`AUTH_REQUIRED`	WebSocket connection missing authentication
`AUTH_INVALID`	WebSocket authentication failed
`SESSION_START_FAILED`	Server failed to start transcription session
`PROVIDER_ERROR`	Transcription provider returned an error
`NO_SESSION`	Tried to stop a session that doesn't exist
`SERVER_ONLY`	Attempted server-only operation in browser

Retry Strategy

For production integrations, implement exponential backoff:

async function withRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 3,
): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (error instanceof RateLimitError && attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
        await new Promise((r) => setTimeout(r, delay));
        continue;
      }
 
      if (
        error instanceof ScribeberryError &&
        error.status &&
        error.status >= 500 &&
        attempt < maxRetries
      ) {
        const delay = Math.pow(2, attempt) * 1000;
        await new Promise((r) => setTimeout(r, delay));
        continue;
      }
 
      throw error; // Don't retry auth errors or client errors
    }
  }
  throw new Error('Max retries exceeded');
}
 
// Usage
const templates = await withRetry(() => sb.templates.list());

Realtime Error Handling

For WebSocket sessions, handle errors via the error event:

const session = sb.realtime.transcribe({ language: 'en-US' });
 
session.on('error', (error) => {
  if (error.message.includes('AUTH_INVALID')) {
    // Token expired — get a new one
    refreshToken();
  } else if (error.message.includes('PROVIDER_ERROR')) {
    // Transcription service issue — notify user
    showNotification('Transcription temporarily unavailable');
  } else {
    console.error('Unexpected error:', error);
  }
});

REST API Error Response Format

When calling the API directly (without the SDK), errors are returned as JSON:

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

On this page