Error Handling - Synthra

Synthra provides comprehensive error handling with typed error classes and automatic retry logic.

Error Types

try {
  await agent.sendMessage(session.id, 'Hello');
} catch (error) {
  if (error instanceof ValidationError) {
    console.log('Invalid parameters');
  } else if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.log(`Retry after ${error.retryAfter}s`);
  } else if (error instanceof SessionError) {
    console.log('Session not found or expired');
  }
}

Error Codes

Code	HTTP	Description
`validation_error`	400	Invalid parameters
`invalid_token`	401	Authentication failed
`session_not_found`	404	Session does not exist
`context_overflow`	413	Context window exceeded
`rate_limit_exceeded`	429	Too many requests
`internal_error`	500	Server-side error

Automatic Retry

const agent = new SynthraAgent({
  apiKey: process.env.SYNTHRA_API_KEY,
  retryConfig: {
    maxRetries: 3,
    initialDelay: 1000,
    backoffMultiplier: 2
  }
});

Error Context

All errors include detailed context:

console.log(error.code);        // Error code
console.log(error.message);     // Human-readable message
console.log(error.statusCode);  // HTTP status
console.log(error.requestId);   // Request ID for support

Error Recovery

async function sendWithRecovery(sessionId, message, userId) {
  try {
    return await agent.sendMessage(sessionId, message);
  } catch (error) {
    if (error instanceof SessionError) {
      const newSession = agent.createSession(userId);
      return await agent.sendMessage(newSession.id, message);
    }
    throw error;
  }
}

All errors include a requestId field. Include this when contacting support.

Do not expose error details to end users. Log errors securely and show user-friendly messages.