Elevenlabs common errors

ElevenLabs Common Errors

Overview

Quick diagnostic reference for ElevenLabs API errors organized by HTTP status code: run the connectivity probe, map the observed status code to a fix, then confirm with the debug checklist. This file is the fast index; the full per-error catalog (payloads + code fixes for every status code) lives in references/error-reference.md.

Prerequisites

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

Instructions

Step 1: Quick Diagnostic

Run the connectivity probe to isolate auth from quota from request problems:

# 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: Map the Status Code to a Fix

Match the HTTP status code (and the detail.status string in the response body) to its row below, then open the linked catalog entry for the exact payload and copy-paste fix:

Status	detail.status	Root cause	First move
401	invalid_api_key	Key missing/malformed/revoked	Re-check ELEVENLABS_API_KEY, regenerate if needed
401	quota_exceeded	Monthly character limit hit	Check usage, upgrade or enable usage-based billing
400	voice_not_found	Bad voice_id in path	GET /v1/voices to list valid IDs
400	text_too_long	TTS text > 5,000 chars	Chunk text with previous_text/next_text
400	model_not_found	Bad model_id string	Use an exact model ID (see catalog)
429	too_many_concurrent_requests	Over plan concurrency	Queue requests to your plan limit
429	system_busy	ElevenLabs under load	Retry with backoff (maxRetries)
422	invalid_voice_sample	Clone audio bad format/too short	MP3/WAV/M4A/FLAC, ≥30s, clean speech
—	WebSocket fails silently	Missing xi_api_key / eleven_v3 on WS	Send key in first WS message, use eleven_flash_v2_5

Full payloads, causes, and fix snippets for every row: references/error-reference.md.

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 catalog)
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

Output

Working through this skill produces:

• A resolved HTTP status code and detail.status string identifying the exact failure.
• The applied fix (corrected key/quota, valid voice_id/model_id, chunked text, request queue, or WebSocket handshake correction).
• A clean re-run of the Step 1 probe returning HTTP 200 from /v1/user and a non-zero voice count, confirming the request path is healthy.

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

Examples

401 after key rotation — the probe returns HTTP 401 with invalid_api_key. The old key is still in the shell env:

echo "${ELEVENLABS_API_KEY:0:8}..."   # confirms which key is loaded
# export the freshly generated key, then re-run the Step 1 probe → HTTP 200

429 under load — batch TTS returns too_many_concurrent_requests. Cap concurrency to the plan limit instead of firing all requests at once:

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

400 on long input — a 7,000-character request returns text_too_long. Split it and preserve 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",
});

See references/error-reference.md for the full payload and fix for every status code above.

Resources

• Full error catalog by status code
• 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.