Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/assemblyai-common-errors/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill assemblyai-common-errors. Copyright stays with the author (MIT).

AssemblyAI Common Errors

Overview

Quick reference for the most common AssemblyAI errors across transcription, streaming, and LeMUR APIs with real error messages and solutions.

Scope and Safety

Troubleshoot only the transcript, streaming session, or request identifier already placed in scope. Treat audio URLs, transcript text, prompts, and authorization headers as sensitive. Use redacted request metadata and official status information; never paste API keys into terminal commands, tickets, or chat.

Prerequisites

• assemblyai package installed
• API key configured
• Access to application logs or console

Instructions

Error 1: Authentication Failed

Error: Authentication error: Invalid API key
Status: 401

Cause: API key is missing, invalid, or revoked.

Solution:

# Test directly without printing the key; load the header from a protected file
# or use the SDK in a local developer session.
curl --config <(printf '%s\n' "header = Authorization: $ASSEMBLYAI_API_KEY") \
  https://api.assemblyai.com/v2/transcript \
  -X GET

Error 2: Transcription Status Error

{ "status": "error", "error": "Download error: unable to download..." }

Cause: The audio URL is not publicly accessible, has expired, or returned non-audio content.

Solution:

// Verify URL is accessible
const response = await fetch(audioUrl, { method: 'HEAD' });
console.log('Content-Type:', response.headers.get('content-type'));
console.log('Status:', response.status);
// Content-Type should be audio/* or video/*

// For private files, upload directly
const transcript = await client.transcripts.transcribe({
  audio: './local-file.mp3',  // SDK handles upload
});

Error 3: Could Not Process Audio

{ "status": "error", "error": "Audio file could not be processed" }

Cause: Corrupted file, unsupported codec, file too short (<200ms), or audio is entirely silent.

Solution:

# Check file with ffprobe
ffprobe -v quiet -print_format json -show_format -show_streams input.mp3

# Convert to a known-good format
ffmpeg -i input.unknown -ar 16000 -ac 1 -f wav output.wav

Error 4: Rate Limit Exceeded

Error: Rate limit exceeded
Status: 429
Header: Retry-After: 30

Cause: Too many concurrent requests. Free tier: 5 streams/min. Paid: 100 streams/min (auto-scales).

Solution:

import { AssemblyAI } from 'assemblyai';

async function transcribeWithBackoff(audioUrl: string, retries = 3) {
  const client = new AssemblyAI({ apiKey: process.env.ASSEMBLYAI_API_KEY! });

  for (let attempt = 0; attempt <= retries; attempt++) {
    try {
      return await client.transcripts.transcribe({ audio: audioUrl });
    } catch (err: any) {
      if (err.status !== 429 || attempt === retries) throw err;
      const delay = Math.pow(2, attempt) * 1000 + Math.random() * 500;
      console.warn(`Rate limited. Retrying in ${delay.toFixed(0)}ms...`);
      await new Promise(r => setTimeout(r, delay));
    }
  }
}

Error 5: Streaming WebSocket Errors

WebSocket error: 4001 Not Authorized
WebSocket error: 4008 Session limit reached
WebSocket error: 4100 Endpoint not found

Error 6: LeMUR Errors

{ "error": "Transcript not found" }
{ "error": "Input text exceeds maximum length" }

Cause: Invalid transcript_ids or total audio exceeds 100-hour limit.

Solution:

// Verify transcript exists before LeMUR call
const transcript = await client.transcripts.get(transcriptId);
if (transcript.status !== 'completed') {
  throw new Error(`Transcript ${transcriptId} status: ${transcript.status}`);
}

// For large inputs, chunk transcript_ids
const chunks = [];
for (let i = 0; i < transcriptIds.length; i += 10) {
  chunks.push(transcriptIds.slice(i, i + 10));
}
for (const chunk of chunks) {
  const { response } = await client.lemur.task({
    transcript_ids: chunk,
    prompt: 'Summarize key points.',
  });
}

Error 7: Unsupported Language

{ "status": "error", "error": "Language not supported" }

Cause: Specified language_code is not available for the selected model.

Solution:

// Use automatic language detection (recommended)
const transcript = await client.transcripts.transcribe({
  audio: audioUrl,
  language_detection: true,  // Auto-detect from 99+ languages
});

console.log('Detected language:', transcript.language_code);

Error 8: Word Boost Not Working

Symptom: Custom terms are still transcribed incorrectly despite word_boost.

Solution:

const transcript = await client.transcripts.transcribe({
  audio: audioUrl,
  word_boost: ['LeMUR', 'AssemblyAI', 'Nova-3'],  // Max 1000 terms
  boost_param: 'high',  // 'low' | 'default' | 'high'
  speech_model: 'best',  // Word boost works with Best model tier
});

Quick Diagnostic Commands

# Check API status
curl -s https://status.assemblyai.com/api/v2/status.json | jq '.status.description'

# Test API connectivity
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: $ASSEMBLYAI_API_KEY" \
  https://api.assemblyai.com/v2/transcript

# Check installed SDK version
npm list assemblyai

# Verify env variable
node -e "console.log(process.env.ASSEMBLYAI_API_KEY ? 'SET' : 'NOT SET')"

Error Handling

Output

Diagnosis returns a redacted status code/category, request or transcript identifier where available, retry decision, and next owner action. It excludes API keys, signed audio URLs, transcript text, and LeMUR prompts.

Examples

For a 429, record the Retry-After value and the opaque workload key, pause further submissions, then retry only after the specified interval and a bounded backoff. For a 401, stop retries, rotate or replace the secret through the approved manager, and verify with the SDK without exposing the credential.

Resources

• AssemblyAI Status Page
• AssemblyAI API Error Codes
• AssemblyAI Support

Next Steps

For comprehensive debugging, see assemblyai-debug-bundle.