Skip to content
Skills Library
Programming · Analysis

deepgram-common-errors

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

Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
6
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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

Triggers from the description

deepgram errordeepgram not workingfix deepgramdeepgram troubleshoottranscription faileddeepgram 401
Original author 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".

How it works

  1. Examples
  2. Overview
  3. Prerequisites
  4. Instructions
  5. Output
  6. Error Handling
  7. Resources
Original SKILL.md headings · 192 lines, 946 words
SKILL.md preview
---
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

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

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

## Resources

- Deepgram Error Handling
- [API Rate Limits](https://developers.deepgram.com/reference/api-rate-limits)
- [Status Page](https://status.deepgram.com)
- [Deepgram Community](https://github.com/orgs/deepgram/discussions)
Files in this package (2)
  • SKILL.md 7 KB
  • references/implementation.md 4 KB

Versions

RepositoryScoreLicence
This page · jeremylongshore/tons-of-skills-marketplace100MIT
HelixDevelopment/agent100MIT

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 2eb09473758c (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100twinmind-common-errors
    Diagnose and fix TwinMind common errors and exceptions. Use when encountering transcription errors, debugging failed requests, or troubleshooting integration issues. Trigger with phrases like "twinmind error", "fix twinmind", "twinmind not working", "debug twinmind", "transcription failed".
  • 100hex-common-errors
    Diagnose and fix Hex common errors and exceptions. Use when encountering Hex errors, debugging failed requests, or troubleshooting integration issues. Trigger with phrases like "hex error", "fix hex", "hex not working", "debug hex".
  • 100exa-common-errors
    Diagnose and fix Exa common errors and exceptions. Use when encountering Exa errors, debugging failed requests, or troubleshooting integration issues. Trigger with phrases like "exa error", "fix exa", "exa not working", "debug exa".
  • 100firecrawl-common-errors
    Diagnose and fix FireCrawl common errors and exceptions. Use when encountering FireCrawl errors, debugging failed requests, or troubleshooting integration issues. Trigger with phrases like "firecrawl error", "fix firecrawl", "firecrawl not working", "debug firecrawl".
  • 100deepgram-webhooks
    Receive and verify Deepgram webhooks (callbacks). Use when setting up Deepgram webhook handlers, processing transcription callbacks, or handling asynchronous transcription results.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.