Diagnose and fix ElevenLabs API errors by HTTP status code.
Use when encountering ElevenLabs errors, debugging failed TTS/STS requests,
or troubleshooting voice cloning and streaming issues.
Trigger: "elevenlabs error", "fix elevenlabs", "elevenlabs not working",
"debug elevenlabs", "elevenlabs 401", "elevenlabs 429", "elevenlabs 400".
Diagnose and fix ElevenLabs API errors by HTTP status code.
Use when encountering ElevenLabs errors, debugging failed TTS/STS requests,
or troubleshooting voice cloning and streaming issues.
Trigger: "elevenlabs error", "fix elevenlabs", "elevenlabs not working",
"debug elevenlabs", "elevenlabs 401", "elevenlabs 429", "elevenlabs 400".
{"detail":{"status":"quota_exceeded","message":"You have insufficient quota to complete this request"}}
Cause: Monthly character limit reached for your plan.
Fix: Check usage at https://elevenlabs.io/app/usage. Upgrade plan, or on Creator+ plans, enable usage-based billing in Subscription settings.
HTTP 400 — Bad Request
Error: voice_not_found
{"detail":{"status":"voice_not_found","message":"Voice not found"}}
Cause: Invalid voice_id in request path.
Fix:
# List your available voices
curl -s https://api.elevenlabs.io/v1/voices \
-H "xi-api-key: ${ELEVENLABS_API_KEY}" | \
jq '.voices[] | {voice_id, name, category}'
Error: text_too_long
{"detail":{"status":"text_too_long","message":"Text is too long. Maximum text length is 5000 characters."}}
Cause: Single TTS request exceeds 5,000 characters.
Fix: Split text into chunks. Use previous_text and next_text parameters to maintain prosody across chunks:
Cause: Voice cloning audio file is corrupt, too short, or wrong format.
Fix: Ensure audio is MP3/WAV/M4A/FLAC, at least 30 seconds, clean speech without music.
WebSocket Errors
Connection fails silently:
WebSocket connection to 'wss://api.elevenlabs.io/v1/text-to-speech/...' failed
Cause: Missing xi_api_key in the first WebSocket message, or using eleven_v3 model (not supported for WebSocket).
Fix:
ws.send(JSON.stringify({
text: " ",
xi_api_key: process.env.ELEVENLABS_API_KEY, // Required in WSmodel_id: "eleven_flash_v2_5", // v3 NOT supported for WS
}));
Step 3: Debug Checklist
Verify API key: curl -s https://api.elevenlabs.io/v1/user -H "xi-api-key: $ELEVENLABS_API_KEY"
Check quota: Look at character_count vs character_limit in the response
Verify voice_id: GET /v1/voices to list valid IDs
Check model_id: Must be an exact match (see table above)
Check request size: Text must be under 5,000 characters
Check concurrency: Are you exceeding your plan's concurrent limit?
