deepgram-common-errors

Diagnose and fix common Deepgram errors and issues. Use when troubleshooting Deepgram API errors, debugging transcription failures, or resolving integration issues. Trigger: "deepgram error", "deepgram not working", "fix deepgram", "deepgram troubleshoot", "transcription failed", "deepgram 401".

Jump to install

Repository: jeremylongshore/tons-of-skills-marketplace
Last source activity: August 19, 2026 at 12:13
Detected SKILL.md language: English
Stars: 2,677
Forks: 392

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

Back to search Back to installation

name	deepgram-common-errors
description	Diagnose and fix common Deepgram errors and issues. Use when troubleshooting Deepgram API errors, debugging transcription failures, or resolving integration issues. Trigger: "deepgram error", "deepgram not working", "fix deepgram", "deepgram troubleshoot", "transcription failed", "deepgram 401".
allowed-tools	Read, Grep, Bash(curl:*)
version	1.13.0
license	MIT
author	Jeremy Longshore <jeremy@intentsolutions.io>
tags	["saas","deepgram","api","debugging","transcription"]
compatibility	Designed for Claude Code

Deepgram Common Errors

Overview

Comprehensive error reference for Deepgram API integration. Covers HTTP error codes, WebSocket errors, transcription quality issues, SDK-specific problems, and audio format debugging with real diagnostic commands.

Prerequisites

Deepgram API key configured
curl available for API testing
Access to application logs

Instructions

Step 1: Quick Diagnostic

# Test API key validity
curl -s -w "\nHTTP %{http_code}\n" \
  'https://api.deepgram.com/v1/projects' \
  -H "Authorization: Token $DEEPGRAM_API_KEY"

# Test transcription endpoint
curl -s -w "\nHTTP %{http_code}\n" \
  -X POST 'https://api.deepgram.com/v1/listen?model=nova-3&smart_format=true' \
  -H "Authorization: Token $DEEPGRAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://static.deepgram.com/examples/Bueller-Life-moves-702702706.wav"}'

Step 2: HTTP Error Reference

Code	Error	Cause	Solution
400	Bad Request	Invalid audio format, bad params	Check audio headers, validate query params
401	Unauthorized	Invalid/expired API key	Regenerate in Console > API Keys
403	Forbidden	Key lacks scope	Create key with `listen` scope for STT
404	Not Found	Wrong endpoint URL	Use `api.deepgram.com/v1/listen`
408	Timeout	Audio too long for sync	Use `callback` param for async
413	Payload Too Large	File exceeds 2GB	Split with `ffmpeg -f segment -segment_time 3600`
429	Too Many Requests

import { LiveTranscriptionEvents } from '@deepgram/sdk';

connection.on(LiveTranscriptionEvents.Error, (error) => {
  console.error('WebSocket error:', {
    message: error.message,
    type: error.type,
  });
});

// Common WebSocket issues:
// 1. Connection closes after ~10s of silence
//    Fix: Send keepAlive() every 8 seconds
connection.keepAlive();

// 2. "Could not process audio" errors
//    Fix: Verify encoding matches what you send
//    Must match: encoding, sample_rate, channels in listen.live() options

// 3. Connection refused / ECONNREFUSED
//    Fix: Check firewall allows wss://api.deepgram.com:443

// 4. Immediate disconnect with 1008 (Policy Violation)
//    Fix: API key invalid or lacks live streaming scope

# Check audio properties with ffprobe
ffprobe -v quiet -print_format json -show_format -show_streams input.wav

# Optimal audio for Deepgram:
# - Sample rate: 8000-48000 Hz (16000 recommended)
# - Channels: 1 (mono) or 2 (stereo for multichannel)
# - Bit depth: 16-bit
# - Format: WAV, MP3, FLAC, OGG, M4A, WebM

# Fix audio quality
ffmpeg -i noisy.wav \
  -af "highpass=f=200,lowpass=f=3000,volume=2" \
  -ar 16000 -ac 1 -acodec pcm_s16le \
  clean.wav

Quality Issue	Likely Cause	Fix
Empty transcript	No speech / too quiet	Boost volume: `-af "volume=3"`
Garbled output	Wrong encoding parameter	Match `encoding` to actual audio format
Missing words	Background noise	Apply noise filter before transcription
Wrong language	Language not specified	Set `language: 'en'` (or correct ISO code)
Low confidence	Poor audio quality	Preprocess to 16kHz mono, noise-reduce
Speaker mismatch	Diarization off	Enable `diarize: true`

// TypeError: createClient is not a function
// You have SDK v5 installed. Use:
import { DeepgramClient } from '@deepgram/sdk';
const dg = new DeepgramClient({ apiKey: process.env.DEEPGRAM_API_KEY });

// TypeError: Cannot read properties of undefined (reading 'prerecorded')
// v5 uses versioned namespaces:
await dg.listen.v1.media.transcribeUrl(source, options);

// "error": { "message": "..." } in result
// Always check the error field:
const { result, error } = await dg.listen.prerecorded.transcribeUrl(source, opts);
if (error) {
  console.error('Deepgram error:', error.message);
  // Don't try to access result — it may be undefined
}

// Python: deepgram.errors.DeepgramApiError
// Catch with try/except:
try:
    response = client.listen.rest.v("1").transcribe_url(source, options)
except Exception as e:
    print(f"API error: {e}")

async function transcribeWithRetry(
  client: any,
  source: any,
  options: any,
  maxRetries = 3
) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const { result, error } = await client.listen.prerecorded.transcribeUrl(
        source, options
      );
      if (error) {
        // 429 and 5xx are retryable
        if (error.status === 429 || error.status >= 500) {
          throw new Error(`Retryable: ${error.status}`);
        }
        throw new Error(`Non-retryable: ${error.message}`);
      }
      return result;
    } catch (err: any) {
      if (attempt === maxRetries || !err.message.startsWith('Retryable')) {
        throw err;
      }
      const delay = Math.min(1000 * Math.pow(2, attempt) + Math.random() * 1000, 30000);
      console.log(`Retry ${attempt + 1}/${maxRetries} in ${Math.round(delay)}ms`);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

Error	Cause	Solution
`ECONNRESET`	Network interruption	Implement retry with backoff
`ETIMEDOUT`	Slow network or large file	Increase timeout, use callback
`ERR_INVALID_ARG_TYPE`	Passing string instead of Buffer to transcribeFile	Use `readFileSync(path)`
`CORS error` (browser)	API called from client-side	Proxy through your server