Assemblyai Common Errors

AssemblyAI Common Errors

Overview

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

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:

# Verify key is set
echo $ASSEMBLYAI_API_KEY

# Test directly
curl -H "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

Resources

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

Next Steps

For comprehensive debugging, see assemblyai-debug-bundle.

Source: jeremylongshore/claude-code-plugins-plus-skills → plugins/saas-packs/assemblyai-pack/skills/assemblyai-common-errors/SKILL.md