How to Easily Debug Live Stream Requests

We’re excited to announce the latest changes to make our live streaming transcription API even easier to use.

Deepgram will now return the request ID and any applicable error messages in the headers for the pre-WebSocket HTTP connection created for all streaming requests.

We’ll show you how to use these below (or you can check out our changelog). First, some background on how the WebSocket protocol works.

When opening a WebSocket connection, the client begins by sending an HTTP request to the server asking for a WebSocket connection. This request may contain credentials, or other configurations.

If the server thinks the HTTP request and any provided credentials/configuration is valid, it will respond with an HTTP 101 code, indicating the connection is accepted and it 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.

This handshake process is abstracted away with most WebSocket libraries—all a developer has to do is call websockets.connect or the library’s equivalent, and the HTTP upgrade is completed under the hood.

If something in the request doesn’t seem right, the server will reject the request and not complete the upgrade from HTTP to WebSocket.

That’s where these usability changes come in. If an HTTP request cannot be upgraded to a WebSocket connection, you can still get an error in the form of an HTTP 4xx or 5xx response, with a body that describes the precise nature of the error. Unfortunately, some WebSocket client libraries do not expose the full response body, meaning no visibility into why your requests are failing. 

However, many libraries give you the ability to view the HTTP headers of a failed handshake, even if you can’t view the response body. Now, if your request is rejected, the HTTP headers will contain both the request ID for debugging, and an error message that may give you insight into why it was rejected.

If the request is successful, you immediately have access to the request ID, rather than needing to wait for it to be returned in a transcript.

Here’s an example using Python. If the request is successful, the request ID is printed. If the request fails, the error message and request ID are printed.

If you run the following code snippet exactly as-is, you should see it fail with an “Invalid credentials” error. To prevent that, swap in a valid Deepgram API key.  (You can generate one here).

import websockets
import json
import asyncio

async def main():
    try:
        async with websockets.connect('wss://api.deepgram.com/v1/listen', 
        extra_headers = { 'Authorization': f'token YOUR_API_KEY' }) as ws:
            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:
        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())

Once a valid API key is added, the script should print out the request ID, then exit.

We’ll be adding more tooling over the coming months to make it even easier to debug streaming errors. Stay tuned!

If you have any feedback about this post, or anything else around Deepgram, we'd love to hear from you. Please let us know in our GitHub discussions .