Twilio error 31403 is an audio output device error that fires when the Voice SDK cannot route audio to the selected output device, either because the device has been disconnected, has failed, or the browser has lost access to it. While callers can still hear the incoming audio if the system falls back to an alternative output device, a 31403 typically means the specifically selected output device is not functioning and needs to be replaced or reselected in the application. The SDK's Device.audio API provides the tools to manage this recovery.
What Causes This Error
A Bluetooth headset disconnecting or running out of battery mid-call is the most frequent real-world trigger for 31403, as the browser's selected output device is no longer available and the SDK cannot route audio to it. The Windows audio service restarting (which can happen after a system update or a driver crash) temporarily makes all audio output devices unavailable, and any active SDK sessions receive 31403 during the restart window. On macOS, switching the output device in System Settings while a call is active can cause the browser to momentarily lose access to the audio output, producing a brief 31403 before the new device is ready. Browsers on iOS do not expose audio output selection through the Web Audio API and HTMLAudioElement.setSinkId is not supported on iOS, so 31403 on iOS typically indicates a system-level audio output failure rather than a device selection issue.
How to Fix It Step by Step
Handle the 31403 error in your Device.on('error') handler by calling navigator.mediaDevices.enumerateDevices() filtered to audiooutput type and checking whether the previously selected device (stored in your application's state) is still present in the list. If the device is absent, call Device.audio.speakerDevices.set(newDeviceId) with the first available output device from the enumeration result to switch to an available speaker automatically. Display a notification in the call UI such as 'Your headset was disconnected. Audio switched to system speakers.' so the user is aware of the device change without being confused by silence or call quality changes. For browsers that support setSinkId (Chrome, Edge, and most Chromium-based browsers), verify that your selected output device ID is still valid before setting it, as passing a stale device ID to setSinkId throws an error that the SDK surfaces as 31403.
How to Prevent It from Recurring
Maintain a live output device list by registering a devicechange event handler with navigator.mediaDevices.addEventListener('devicechange') and re-enumerating output devices whenever the event fires, updating your application's device state immediately when devices are added or removed. Listen to the Device.audio.on('deviceChange') event provided by the Voice SDK's audio API, which fires specifically when audio devices change in a way that affects the SDK's audio routing, and use it to trigger an automatic device re-selection and a user-facing notification. Implement output device validation in your pre-call setup by attempting to play a silent test tone through the selected output device using an HTMLAudioElement with the setSinkId method set to the desired device ID, and falling back to the default output device if the setSinkId call throws. Show audio device status indicators in your call interface that display the currently active input and output devices by label, making it immediately obvious to the user when the device has changed or when a fallback is in use.
When to Call a Specialist
If 31403 errors are occurring on users' computers without any visible device disconnection (the headset is plugged in and appears in device manager), the issue may be a Windows audio session policy that interrupts browser audio output under specific conditions, such as an exclusive mode conflict with another application's audio session. A specialist can use Windows audio diagnostics tools to identify which application is claiming exclusive mode on the audio output device and recommend configuration changes to allow shared access. For applications deployed in contact center environments where audio device reliability is business-critical, a specialist can implement a comprehensive audio health monitoring system that proactively detects device failures, performs automatic failover, and logs device events for quality assurance review.
Conclusion
Error 31403 is an audio output device failure that is handled by implementing devicechange event listeners, automatic output device fallback using Device.audio.speakerDevices.set(), and clear user-facing notifications when a device change occurs. If this error is blocking your production system, contact our team and we will diagnose and fix it within the hour.
Ready to Transform Your Business Communications?
Get a free consultation with our VoIP experts and discover how we can help you save costs, improve efficiency, and scale your business.
Comments (0)
Join the discussion and share your thoughts (AI-moderated for quality)
Be the first to comment
No comments yet. Share your thoughts below.