OpenParable
Skip to content
← Back to skills

Deepgram Common Errors

Testing & Quality
deepgram-common-errors

Deepgram Common Errors is an Agent Skill for testing & quality published in the jeremylongshore/claude-code-plugins-plus-skills repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/HEAD/plugins/saas-packs/deepgram-pack/skills/deepgram-common-errors/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/deepgram-common-errors, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

CodeErrorCauseSolution
400Bad RequestInvalid audio format, bad paramsCheck audio headers, validate query params
401UnauthorizedInvalid/expired API keyRegenerate in Console > API Keys
403ForbiddenKey lacks scopeCreate key with listen scope for STT
404Not FoundWrong endpoint URLUse api.deepgram.com/v1/listen
408TimeoutAudio too long for syncUse callback param for async
413Payload Too LargeFile exceeds 2GBSplit with ffmpeg -f segment -segment_time 3600
429Too Many RequestsConcurrency limit hitImplement backoff, check plan limits
500Internal ErrorDeepgram server errorRetry with backoff, check status.deepgram.com
502Bad GatewayUpstream failureRetry after 5-10 seconds
503Service UnavailableMaintenance/overloadCheck status.deepgram.com, retry later

Step 3: WebSocket Errors

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

Step 4: Transcription Quality Issues

# 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 IssueLikely CauseFix
Empty transcriptNo speech / too quietBoost volume: -af "volume=3"
Garbled outputWrong encoding parameterMatch encoding to actual audio format
Missing wordsBackground noiseApply noise filter before transcription
Wrong languageLanguage not specifiedSet language: 'en' (or correct ISO code)
Low confidencePoor audio qualityPreprocess to 16kHz mono, noise-reduce
Speaker mismatchDiarization offEnable diarize: true

Step 5: SDK-Specific Errors

// 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}")

Step 6: Retry Pattern for Transient Errors

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));
    }
  }
}

Output

  • API diagnostic curl commands
  • HTTP error reference with solutions
  • WebSocket error handling patterns
  • Audio quality debugging with ffprobe/ffmpeg
  • SDK version-specific error fixes
  • Retry pattern for transient failures

Error Handling

ErrorCauseSolution
ECONNRESETNetwork interruptionImplement retry with backoff
ETIMEDOUTSlow network or large fileIncrease timeout, use callback
ERR_INVALID_ARG_TYPEPassing string instead of Buffer to transcribeFileUse readFileSync(path)
CORS error (browser)API called from client-sideProxy through your server

Resources