elevenlabs-common-errors

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".
allowed-tools	Read, Grep, Bash(curl:*), Bash(node:*)
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","voice","ai","elevenlabs","debugging","errors"]
compatible-with	claude-code

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