elevenlabs-common-errors

ElevenLabs Common Errors

Overview

Quick diagnostic reference for ElevenLabs API errors organized by HTTP status code, with real error messages, causes, and solutions.

Prerequisites

• ElevenLabs SDK installed
• API key configured
• Access to error logs or console output

Instructions

Step 1: Quick Diagnostic

# Test API connectivity and auth
curl -s -w "\nHTTP %{http_code}" \
  https://api.elevenlabs.io/v1/user \
  -H "xi-api-key: ${ELEVENLABS_API_KEY}"

# Check character quota
curl -s https://api.elevenlabs.io/v1/user \
  -H "xi-api-key: ${ELEVENLABS_API_KEY}" | \
  jq '.subscription | {tier, character_count, character_limit}'

# List available voices (confirms API access)
curl -s https://api.elevenlabs.io/v1/voices \
  -H "xi-api-key: ${ELEVENLABS_API_KEY}" | jq '.voices | length'

Step 2: Error Reference

---

HTTP 401 — Authentication / Quota

Error: invalid_api_key

{
  "detail": {
    "status": "invalid_api_key",
    "message": "Invalid API key"
  }
}

Cause: API key is missing, malformed, or revoked. Fix:

# Verify key is set
echo "${ELEVENLABS_API_KEY:0:8}..."

# Test with curl
curl -s https://api.elevenlabs.io/v1/user -H "xi-api-key: ${ELEVENLABS_API_KEY}"

# Regenerate at: https://elevenlabs.io/app/settings/api-keys

Error: quota_exceeded

{
  "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:

const audio = await client.textToSpeech.convert(voiceId, {
  text: currentChunk,
  previous_text: previousChunk,  // Helps maintain flow
  next_text: nextChunk,          // Helps maintain flow
  model_id: "eleven_multilingual_v2",
});

Error: model_not_found

{
  "detail": {
    "status": "model_not_found",
    "message": "Model not found"
  }
}

Cause: Invalid model_id string. Fix: Use exact model IDs: eleven_v3, eleven_multilingual_v2, eleven_flash_v2_5, eleven_turbo_v2_5, eleven_monolingual_v1, eleven_english_sts_v2.

---

HTTP 429 — Rate Limited

Error: too_many_concurrent_requests

{
  "detail": {
    "status": "too_many_concurrent_requests",
    "message": "Too many concurrent requests"
  }
}

Cause: Exceeded concurrent request limit for your plan. Fix: Queue requests. Concurrency limits by plan:

Plan	Concurrent Requests
Free	2
Starter	3
Creator	5
Pro	10
Scale	15
Business	15

import PQueue from "p-queue";
const queue = new PQueue({ concurrency: 5 }); // Match your plan
await queue.add(() => client.textToSpeech.convert(voiceId, options));

Error: system_busy

{
  "detail": {
    "status": "system_busy",
    "message": "Our services are experiencing high traffic"
  }
}

Cause: ElevenLabs servers under heavy load. Fix: Retry with exponential backoff (the SDK does this automatically with maxRetries):

const client = new ElevenLabsClient({
  maxRetries: 3, // Auto-retries 429 and 5xx
});

---

HTTP 422 — Validation Error

Error: invalid_voice_sample

{
  "detail": {
    "status": "invalid_voice_sample",
    "message": "Invalid audio file"
  }
}

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 WS
  model_id: "eleven_flash_v2_5",  // v3 NOT supported for WS
}));

Step 3: Debug Checklist

1. Verify API key: curl -s https://api.elevenlabs.io/v1/user -H "xi-api-key: $ELEVENLABS_API_KEY"
2. Check quota: Look at character_count vs character_limit in the response
3. Verify voice_id: GET /v1/voices to list valid IDs
4. Check model_id: Must be an exact match (see table above)
5. Check request size: Text must be under 5,000 characters
6. Check concurrency: Are you exceeding your plan's concurrent limit?
7. Check ElevenLabs status: https://status.elevenlabs.io

Error Handling

HTTP	Error	Retryable	Action
400	Bad request	No	Fix request parameters
401	Auth/quota	No	Check key or upgrade plan
404	Not found	No	Verify voice_id/model_id
422	Validation	No	Fix input data format
429	Rate limit	Yes	Backoff + queue requests
500+	Server error	Yes	Retry with backoff

Resources

• ElevenLabs Error Messages
• API Error 429 Help
• API Error 401 Help
• ElevenLabs Status

Next Steps

For comprehensive debugging, see elevenlabs-debug-bundle. For rate limit handling, see elevenlabs-rate-limits.