Error Handling - OneBudd Documentation

Error Event Structure

When an error occurs, the server sends an error event with a code, message, and fatal flag indicating whether the session is still usable:

Error Event

// Error event structure
{
  "type": "error",
  "version": "1",
  "session_id": "sess_abc123",
  "timestamp": 1699900000000,
  "payload": {
    "code": "stt_failed",
    "message": "Speech recognition failed: invalid audio format",
    "fatal": false
  }
}

Fatal vs Non-Fatal Errors

Fatal Errors

Session is terminated. Client must establish a new connection and re-authenticate with session.init.

Non-Fatal Errors

Session continues. The current operation failed but you can retry or continue with other operations.

Error Codes

Code	Fatal	Description
`auth_failed`	Yes	Invalid or expired auth_token
`session_expired`	Yes	Session timed out (default: 1 hour)
`session_not_found`	Yes	Session ID not recognized
`rate_limited`	No	Too many requests - slow down
`stt_failed`	No	Speech recognition error (check audio format)
`llm_failed`	No	LLM processing error
`tts_failed`	No	Text-to-speech generation error
`invalid_event`	No	Malformed event structure
`invalid_audio`	No	Audio format not supported
`server_error`	Yes	Internal server error - reconnect

Handling Errors in Code

Use the SDK's error event to handle errors appropriately:

Error Handling Example

import { OneBuddClient } from '@onebudd/sdk';

const client = new OneBuddClient({ baseUrl: 'wss://api.onebudd.com' });

client.on('error', ({ code, message, fatal }) => {
  console.error(`Error [${code}]: ${message}`);
  
  if (fatal) {
    // Session is terminated - must reconnect
    console.log('Fatal error - reconnecting...');
    reconnect();
  } else {
    // Non-fatal - session continues
    // May want to notify user or retry operation
    showUserNotification(message);
  }
});

async function reconnect() {
  try {
    await client.startSession({ auth_token: 'sk_live_xxx' });
    console.log('Reconnected successfully');
  } catch (error) {
    console.error('Reconnection failed:', error);
    // Implement exponential backoff
    setTimeout(reconnect, 5000);
  }
}

Best Practices

Implement Reconnection

Use exponential backoff when reconnecting after fatal errors to avoid overwhelming the server.

Log Error Details

Log the error code, message, and session_id for debugging. Include timestamp for correlation.

User Feedback

Show user-friendly messages for common errors. "Please try again" is better than error codes.

Validate Audio Format

Most STT errors come from incorrect audio format. Verify 16kHz, mono, 16-bit PCM before sending.