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.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>
compatible-with	claude-code, codex, openclaw
tags	["saas","deepgram","api","debugging","transcription"]

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