Deepgram Common ErrorsSAFE

Model-agnostic agent-skills platform with a harness-free canonical layer, verified adapters, and the ccpi package manager. Explore at tonsofskills.com.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
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 <[email protected]>
tags:
- saas
- deepgram
- api
- debugging
- transcription
compatibility: Designed for Claude Code
---
# Deepgram Common Errors

## Examples

For a failed transcription request, record its opaque correlation ID, environment, model, status class, and redacted timing. Check media format, credentials, timeout, and rate-limit state with a non-sensitive fixture; if the condition remains, escalate with the minimal redacted bundle rather than attaching customer audio or transcript text.

## 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

```bash
# 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 | Concurrency limit hit | Implement backoff, check plan limits |
| 500 | Internal Error | Deepgram server error | Retry with backoff, check status.deepgram.com |
| 502 | Bad Gateway | Upstream failure | Retry after 5-10 seconds |
| 503 | Service Unavailable | Maintenance/overload | Check status.deepgram.com, retry later |

### Step 3: WebSocket Errors

```typescript
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

```bash
# 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` |

### Step 5: SDK-Specific Errors

```typescript
// 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

```typescript
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 === 42

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.