WebSocket DATA & NET Errors When Live Streaming

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.

ℹ️

Our live streaming starter kit 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 Connections

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 4xx or 5xx response.

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.

For your client application to close the WebSocket connection with Deepgram, send a JSON message to the server: { 'type': 'CloseStream' }. The server will interpret it as a shutdown command, which means it will finish processing whatever data is still has cached, send the response to the client, send a summary metadata object, and then terminate the WebSocket connection.

🚧

Previously, Deepgram allowed connection closures by sending an empty byte message (for example, Uint8Array(0) in JavaScript, or b'' in Python). Though this method is still available, it should be considered deprecated. If you notice your WebSocket connection closing suddenly but without an error, you may be sending an empty byte and triggering a closure. One way to avoid sending an empty byte accidentally is to add a conditional to check if the length of your audio packet is 0 before sending.

Using KeepAlive to Maintain Connection

KeepAlive serves as a crucial mechanism for maintaining an uninterrupted connection with Deepgram's servers, allowing you to optimize your audio streaming experience while minimizing costs. By periodically sending KeepAlive messages, you can ensure that the WebSocket connection remains open, preventing timeouts and maintaining communication with Deepgram's servers. This helps avoid abrupt closures and reduces the risk of encountering NET-0001 errors, which occur when no audio data is received within a 10-second window.

To implement KeepAlive, periodically send a text-based WebSocket message in JSON format with the type "KeepAlive" to Deepgram's servers. { "type": "KeepAlive" }. Be sure to send the KeepAlive message as a text WebSocket message, as sending it as a binary message may result in incorrect handling and could lead to connection issues. For more detailed implementation instructions and troubleshooting, refer to our documentation on using KeepAlive.

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-id HTTP header, which contains the request ID.
• Requests that do not successfully upgrade to a WebSocket connection also include the dg-error HTTP 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

The level of access you have to the custom HTTP headers returned by the Deepgram API depends on the WebSocket library you are using. For example, for security reasons, browser-based WebSocket libraries like the JavaScript WebSocket library only allow access to HTTP header information for successful WebSocket connections.

Code Samples

⚠️

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.

import websockets
import json
import asyncio

async def main():
    try:
        async with websockets.connect('wss://api.deepgram.com/v1/listen',
        # Remember to replace the YOUR_DEEPGRAM_API_KEY placeholder with your Deepgram API Key
        extra_headers = { 'Authorization': f'token YOUR_DEEPGRAM_API_KEY' }) as ws:
            # If the request is successful, print the request ID from the HTTP header
            print('🟢 Successfully opened connection')
            print(f'Request ID: {ws.response_headers["dg-request-id"]}')
            await ws.send(json.dumps({
                'type': 'CloseStream'
            }))
    except websockets.exceptions.InvalidStatusCode as e:
        # If the request fails, print both the error message and the request ID from the HTTP headers
        print(f'🔴 ERROR: Could not connect to Deepgram! {e.headers.get("dg-error")}')
        print(f'🔴 Please contact Deepgram Support with request ID {e.headers.get("dg-request-id")}')

asyncio.run(main())

const WebSocket = require('ws');
const ws = new WebSocket('wss://api.deepgram.com/v1/listen', {
    headers: {
      // Remember to replace the YOUR_DEEPGRAM_API_KEY placeholder with your Deepgram API Key
      Authorization: 'Token YOUR_DEEPGRAM_API_KEY',
    },
});
// For security reasons, browser-based WebSocket libraries only allow access to HTTP header information for successful WebSocket connections
// If the request is successful, return the HTTP header that contains the request ID
ws.on('upgrade', function message(data) {
    console.log(data.headers['dg-request-id']);
});

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:

After sending the Close message, our endpoint considers the WebSocket connection closed and will close the underlying TCP connection.

Troubleshooting 1008 - 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:

1. 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.

2. 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.

Troubleshooting 1011 - 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:

1. Check the status of Deepgram's systems to confirm that Deepgram is operational.

2. 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.

Troubleshooting 1011 - 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, this error often occurs because the data you intend to send to Deepgram is not being sent. If there is a period of time before your system begins to send audio, Deepgram may close the websocket connection. It is therefore important to send audio to Deepgram within ~10 seconds after opening the websocket. If Deepgram does not receive enough audio to send a message over the websocket within the first 10 seconds of it opening, the websocket connection will be closed. You can send silent audio because Deepgram will respond with an empty transcript. Sending a KeepAlive message to Deepgram will not prevent the websocket from closing until at least one message has been sent by Deepgram.

Another reason for this error is that you have sent all the audio you intend to send, but Deepgram is still waiting for additional context in order to provide a more accurate transcription. This is common if you are sending short utterances or if you have reached the end of your audio. Send a CloseStream message to tell Deepgram that you have sent all the audio you plan to send and that it should process what it has received before closing the WebSocket connection.

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.