Error Handling

The SDK provides structured error handling with typed error codes. This guide covers all error types and recommended recovery patterns.

Error Structure


interface VoiceAgentError {
  code: VoiceAgentErrorCode
  message: string
}

Error Codes

Code	Description
`MIC_PERMISSION_DENIED`	User denied microphone access
`INVALID_API_KEY`	API key is missing, malformed, or revoked
`INSUFFICIENT_CREDITS`	Account has no credits remaining
`CONCURRENCY_LIMIT`	Too many active sessions for this API key
`AGENT_NOT_FOUND`	Agent name doesn’t exist or is deleted
`NETWORK_ERROR`	Network request failed
`CONNECTION_FAILED`	Voice connection couldn’t be established

Handling Errors

With VoiceAgent Component


<VoiceAgent
  apiKey="..."
  agentName="..."
  onError={(error) => {
    switch (error.code) {
      case 'MIC_PERMISSION_DENIED':
        showMicrophoneHelp()
        break
      case 'INSUFFICIENT_CREDITS':
        showUpgradePrompt()
        break
      case 'CONCURRENCY_LIMIT':
        showBusyMessage()
        break
      default:
        showGenericError(error.message)
    }
  }}
/>

With Hooks


function VoiceUI() {
  const { connect, error } = useVoiceSession()
 
  if (error) {
    return <ErrorDisplay error={error} onRetry={connect} />
  }
 
  return <VoiceControls />
}

Error Recovery Patterns

MIC_PERMISSION_DENIED

The user blocked microphone access. Requires user action.


function MicrophonePermissionGuide() {
  return (
    <div>
      <h3>Microphone Access Required</h3>
      <ol>
        <li>Click the lock icon in your browser's address bar</li>
        <li>Find "Microphone" in permissions</li>
        <li>Change from "Block" to "Allow"</li>
        <li>Refresh the page</li>
      </ol>
      <button onClick={() => window.location.reload()}>Refresh</button>
    </div>
  )
}

INSUFFICIENT_CREDITS

Direct users to purchase more credits.


function UpgradePrompt() {
  return (
    <div>
      <h3>Out of Credits</h3>
      <p>Your account needs more credits to make calls.</p>
      <a href="https://dashboard.vocobase.com/billing">
        Purchase Credits
      </a>
    </div>
  )
}

CONCURRENCY_LIMIT

Too many simultaneous sessions. Wait and retry.


function BusyMessage({ onRetry }) {
  return (
    <div>
      <h3>All Lines Busy</h3>
      <p>Please wait a moment and try again.</p>
      <button onClick={onRetry}>Try Again</button>
    </div>
  )
}

NETWORK_ERROR

Network request failed. Usually transient.


function NetworkError({ onRetry }) {
  const { isOnline } = useNetworkStatus()
 
  return (
    <div>
      <h3>Network Error</h3>
      {!isOnline ? (
        <p>You appear to be offline.</p>
      ) : (
        <p>Unable to reach our servers. This may be temporary.</p>
      )}
      <button onClick={onRetry} disabled={!isOnline}>
        Try Again
      </button>
    </div>
  )
}

Error Utilities


import {
  createError,
  getDefaultErrorMessage,
  ERROR_MESSAGES
} from '@vocobase/voice-client-sdk'
 
// Create a typed error
const error = createError('INSUFFICIENT_CREDITS', 'Custom message')
 
// Get default message for a code
const message = getDefaultErrorMessage('MIC_PERMISSION_DENIED')
 
// Access all default messages
console.log(ERROR_MESSAGES)