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".
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Instruções da origem · Visualização somente leitura
name
elevenlabs-common-errors
description
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?
