Troubleshooting WebSocket DATA and NET Errors When Live Streaming Audio
Successfully integrating different systems can be complex, especially when handling real-time audio. When you begin to work with Deepgram’s live streaming API, you may encounter some errors. If you do, don’t worry—we’re here to help!
Our streaming test suite provides sample code to help you get started. Before you begin to build your own integration, we recommend running our test suite code at least once to ensure that you can successfully stream sample audio to Deepgram.
WebSocket is a protocol that makes it possible to open a two-way interactive communication session between a user’s browser and a server. When a WebSocket connection is established, you can send messages to a server and receive event-driven responses from the server without having to poll the server for a reply. WebSocket can be useful when you want to work with any real-time updated or continuous streams of data that are being transmitted over the network.
Establishing a WebSocket Connection
To initiate a WebSocket connection, the client sends an HTTP handshake request to the server asking the server to upgrade the connection to a WebSocket connection. This request may contain configuration options passed as URL query parameters. If operating on the server side, the request may also contain additional headers that can be used for authentication or other purposes. (For security reasons, browser-based WebSocket libraries restrict access to sending and receiving headers.)
Most WebSocket libraries abstract the handshake process. A developer only needs to call
websockets.connect (or the library’s equivalent), and the library handles the rest of the implementation of the HTTP upgrade.
If the server thinks the HTTP request and any provided configuration options or credentials are valid, it responds with an HTTP
101 code, indicating that the connection is accepted and that the server plans to switch the connection to the WebSocket protocol. After the HTTP
101 response is sent, the client can start to send and receive data from the WebSocket as usual.
If something in the HTTP request doesn’t seem right, the server rejects the request and does not complete the upgrade from HTTP to WebSocket. If the server cannot upgrade an HTTP request to a WebSocket connection, you will receive an error in the form of an HTTP
Closing the WebSocket Connection
A successfully opened WebSocket connection will stay alive until it is eventually closed by either the client or the server. When this occurs, a WebSocket Close frame (WebSocket Protocol specification, section 5.5.1) will be returned. The body of the Close frame will indicate the reason for closing using one of the specification’s pre-defined status codes followed by a UTF-8-encoded payload that represents the reason for the error. After sending a Close message, the endpoint considers the WebSocket connection closed and will close the underlying TCP connection.
Debugging Websocket Errors
Websocket errors that you may experience fall into two major categories:
- Failure to connect to Deepgram
- Abrupt closure of the WebSocket connection after it has been established
Failure to Connect to Deepgram
If you’re unable to connect to Deepgram, then during the upgrade process, the Deepgram API provides custom HTTP headers that contain debugging information:
- Regardless of the success or failure of the WebSocket upgrade, all requests include the
dg-request-idHTTP header, which contains the request ID.
- Requests that do not successfully upgrade to a WebSocket connection also include the
dg-errorHTTP header, which contains a detailed error message concerning why the connection could not be upgraded. This error message is also sent back in the body of the HTTP response.
Accessing WebSocket Headers
In the following code samples, be sure to replace
YOUR_DEEPGRAM_API_KEY with your Deepgram API Key. (You can generate one using the Deepgram Console). Otherwise, the code will fail with an
Invalid credentials error.
Abrupt WebSocket Closures
If Deepgram encounters an error during real-time streaming, the Deepgram API returns a WebSocket Close frame (WebSocket Protocol specification, section 5.5.1). The body of the Close frame indicates the reason for closing using one of the specification’s pre-defined status codes followed by a UTF-8-encoded payload that represents the reason for the error. Current codes and payloads in use include:
|The payload cannot be decoded as audio. The payload either is not audio data or is a codec unsupported by Deepgram.|
|The service has not transmitted a Text frame to the client within the timeout window. This may indicate an internal issue with Deepgram’s systems, or Deepgram may have not received enough audio data to transcribe a frame.|
|The service has not received a Binary frame from the client within the timeout window. This may indicate an internal issue with Deepgram’s systems, the client’s systems, or the network connecting them.|
After sending the Close message, our endpoint considers the WebSocket connection closed and will close the underlying TCP connection.
DATA-0000 WebSocket Errors
If you’re receiving a
1008 code with a
DATA-0000 payload, Deepgram can’t decode the audio data you’re sending.
Often, this error is caused because the data you intend to send to Deepgram is not being sent. To troubleshoot:
Start by closely inspecting the data being sent to Deepgram. One way to do this is by writing the audio data to a file to make sure it contains the expected audio and can be played back.
If the audio data is valid, check whether the audio being sent is raw or containerized. If the audio is raw, frequently this error occurs because the encoding and sample rate parameters have not been set explicitly or have been set incorrectly, either of which will cause Deepgram to be unable to decode the audio. To learn more, see our guide on determining your audio format.
NET-0000 WebSocket Errors
If you’re receiving a
1011 code with a
NET-0000 payload, Deepgram wasn’t able to generate a transcript for the audio data you’re sending before the system timed out. To troubleshoot:
Check the status of Deepgram’s systems to confirm that Deepgram is operational.
If all Deepgram systems are green, contact Support. When contacting support, be sure to include:
- the error received
- the request ID
- a sample of your audio
- any related code you’re able to share.
NET-0001 WebSocket Errors
If you’re receiving a
1011 code with a
NET-0001 payload, Deepgram didn’t receive any audio from you before the system timed out.
As with the
1008 code, often this error is caused because the data you intend to send to Deepgram is not being sent. In some cases, if there is a period of time before your system begins to send audio, you may need to send silent audio to Deepgram to keep the connection open.
Other reasons for this error include potential network issues. To troubleshoot, test your network by making a cURL request to Deepgram using a Deepgram-hosted audio file. To learn how to do this, you can follow along with our guide on generating transcripts from the terminal. If you’re unable to get a transcript using this method, something in your network may be preventing you from connecting to Deepgram.
Another way to check that audio is successfully leaving your network is to capture a sample of your network traffic using a packet sniffer and network analysis tool like Wireshark.
If you would like to provide general feedback about our products, please start a new GitHub Discussion.
Some related guides that may be of interest include: