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 with "elevenlabs error", "fix elevenlabs", "elevenlabs not working", "debug elevenlabs", "elevenlabs 401", "elevenlabs 429", "elevenlabs 400".
allowed-tools	Bash(curl:*), Bash(node:*)
version	1.6.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","voice","ai","elevenlabs","debugging","errors"]
compatibility	Designed for Claude Code

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 in path