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:
echo $ASSEMBLYAI_API_KEY
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:
const response = await fetch(audioUrl, { method: 'HEAD' });
console.log('Content-Type:', response.headers.get('content-type'));
console.log('Status:', response.status);
const transcript = await client.transcripts.transcribe({
audio: './local-file.mp3',
});
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:
ffprobe -v quiet -print_format json -show_format -show_streams input.mp3
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:
const transcript = await client.transcripts.get(transcriptId);
if (transcript.status !== 'completed') {
throw new Error(`Transcript ${transcriptId} status: ${transcript.status}`);
}
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:
const transcript = await client.transcripts.transcribe({
audio: audioUrl,
language_detection: true,
});
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'],
boost_param: 'high',
speech_model: 'best',
});
Quick Diagnostic Commands
curl -s https://status.assemblyai.com/api/v2/status.json | jq '.status.description'
curl -s -o /dev/null -w "%{http_code}" \
-H "Authorization: $ASSEMBLYAI_API_KEY" \
https://api.assemblyai.com/v2/transcript
npm list assemblyai
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.
