Error Codes

The widget emits structured errors through the error event and surfaces them in logs. Each error carries a stable code (e.g. AUTH_001), a category, a human-readable message, and optionally a details payload with additional context.

TraiseWidget.on('error', (err) => {
  if (err.category === 'auth') {
    // handle auth failure (bad API key, account disabled, etc.)
  }
  console.error(err.code, err.message, err.details);
});

Codes are grouped by category. Use the category to branch on broad failure classes; use the code when you need precise behaviour for a specific case.

Authentication

Code	Meaning
`AUTH_001`	Invalid API key
`AUTH_002`	API key expired or revoked
`AUTH_003`	Account not found

Voice

Code	Meaning
`VOICE_001`	Microphone permission denied
`VOICE_002`	Call failed to connect
`VOICE_003`	Voice token refresh failed
`VOICE_004`	No voice device available

SMS

Code	Meaning
`SMS_001`	Message send failed
`SMS_002`	Invalid phone number
`SMS_003`	SMS room creation failed

WebSocket / Network

Code	Meaning
`WS_001`	WebSocket connection failed
`WS_002`	Max reconnection attempts reached
`WS_003`	Connection rejected by server

API

Code	Meaning
`API_001`	Request timeout
`API_002`	Server error
`API_003`	Rate limited

Handling Errors

Ignore vs. surface

Not every error needs user-facing handling. Network blips that auto-recover (WS_001 when reconnection succeeds on the next attempt) can be logged and ignored. Auth failures (AUTH_001, AUTH_002) usually warrant surfacing — the widget can't recover on its own and the integrator needs to refresh or rotate the API key.

Unknown codes

If the widget emits a code not listed above, it will still carry a category of api and a descriptive message. Catch-all branches on err.category are safe; switches on err.code should include a default.

Authentication​

Voice​

SMS​

WebSocket / Network​

API​

Handling Errors​

Ignore vs. surface​

Unknown codes​