deepgram-common-errors

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 <[e-mail]>
tags	["saas","deepgram","api","debugging","transcription"]
compatibility	Designed for Claude Code, also compatible with Codex and OpenClaw

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