ElevenLabs Common Errors Skill

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

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?
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

Next Steps

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

Agent Skills: ElevenLabs Common Errors

Install this agent skill to your local

Skill Files