Deepgram Common Errors

Table of Contents

• Overview

• Prerequisites

• Instructions

• Output

• Error Handling

• Examples

• Resources

Overview

Comprehensive guide to diagnosing and fixing common Deepgram integration errors including authentication, audio processing, rate limiting, WebSocket, and transcription quality issues.

Prerequisites

• Deepgram API key configured

• Access to application logs

• curl available for API testing

Instructions

Step 1: Quick Diagnostic

Test API connectivity with a simple curl request to verify key and endpoint.

Step 2: Identify Error Category

Match the HTTP status code to the error reference table below.

Step 3: Apply Fix

Follow the specific resolution for the error type.

Step 4: Verify Resolution

Re-run the diagnostic to confirm the fix works.

Output

• Error identified and categorized

• Root cause determined

• Fix applied and verified

Error Handling

Error Reference Table

HTTP Code Error Code Common Cause Solution

400 BAD_REQUEST Invalid audio format Check audio encoding, validate file header

401 INVALID_AUTH Missing/invalid API key Verify DEEPGRAM_API_KEY , check header format

403 ACCESS_DENIED Permission denied Check key permissions, verify account tier

404 NOT_FOUND Invalid endpoint Check API URL path

413 PAYLOAD_TOO_LARGE File too large Split audio with ffmpeg -f segment

429 RATE_LIMIT_EXCEEDED Too many requests Implement exponential backoff with jitter

500 INTERNAL_ERROR Server error Retry with backoff, check status page

503 SERVICE_UNAVAILABLE Service down Check status.deepgram.com

WebSocket Errors

• Connection Refused: Check firewall rules, verify WSS URL

• Connection Dropped: Implement KeepAlive messages every 10 seconds

Transcription Quality Issues

• Check audio sample rate (16kHz recommended)

• Verify audio is mono or stereo

• Test with known-good audio file

• Check language setting matches audio content

• Use alternatives: 3, words: true for debugging confidence scores

Examples

Quick API Test

set -euo pipefail curl -X POST 'https://api.deepgram.com/v1/listen?model=nova-2'
-H "Authorization: Token $DEEPGRAM_API_KEY"
-H "Content-Type: audio/wav"
--data-binary @test.wav

Validate Audio File Header

Check first bytes: 52494646 (WAV), fff3/fffb (MP3), 664c6143 (FLAC), 4f676753 (OGG).

See detailed implementation for advanced patterns.

Resources

• Deepgram Error Codes

• Deepgram Status Page

• Deepgram Support