AssemblyAI Common Errors Skill

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

| Code | Meaning | Solution | |------|---------|----------| | 4001 | Bad API key or expired token | Refresh token via client.streaming.createTemporaryToken() | | 4008 | Max concurrent streams reached | Wait for existing streams to close | | 4100 | Wrong WebSocket URL | Use wss://api.assemblyai.com/v2/realtime/ws | | 4010 | Audio too short/no speech | Ensure microphone is capturing audio |

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

| Error | HTTP Code | Retryable | Action | |-------|-----------|-----------|--------| | Auth error | 401 | No | Fix API key | | Not found | 404 | No | Check transcript ID | | Rate limit | 429 | Yes | Exponential backoff | | Server error | 500-503 | Yes | Retry after delay | | Download error | N/A | Maybe | Check audio URL accessibility |

Resources

Next Steps

For comprehensive debugging, see assemblyai-debug-bundle.

Agent Skills: AssemblyAI Common Errors

Install this agent skill to your local

Skill Files