Agent skill · data analytics · jeremylongshore
deepgram-common-errors
Diagnose and fix common Deepgram errors and issues.
Why this skill is useful
Provides specific diagnostic commands and error handling procedures for Deepgram API integration that the AI wouldn't reliably generate on its own.
What it needs
Requires curl, ffmpeg installed locally. Requires deepgram account access. About 4k tokens when loaded. Last updated 2026-08-07. 2,604 stars on the source repository.
What this skill does
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 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 -segmenttime 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 Step 4: Transcription Quality Issues 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 IS …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/deepgram-common-errors