Error Handling

Best practices for handling errors and exceptions in the ElevenLabs SDK

Overview

The ElevenLabs Python SDK provides a comprehensive set of exception types that map to HTTP status codes. Proper error handling ensures your application can gracefully handle API errors and provide meaningful feedback to users.

Exception Types

The SDK includes the following exception types, all inheriting from ApiError:

BadRequestError (400)

Raised when the request is malformed or contains invalid parameters.

from elevenlabs import ElevenLabs, BadRequestError

client = ElevenLabs(api_key="YOUR_API_KEY")

try:
    audio = client.text_to_speech.convert(
        text="",  # Empty text
        voice_id="invalid-id",
        model_id="eleven_multilingual_v2"
    )
except BadRequestError as e:
    print(f"Bad request: {e.body}")
    print(f"Status code: {e.status_code}")  # 400

UnauthorizedError (401)

Raised when the API key is missing or invalid.

from elevenlabs import ElevenLabs, UnauthorizedError

try:
    client = ElevenLabs(api_key="invalid_key")
    voices = client.voices.search()
except UnauthorizedError as e:
    print("Invalid API key. Please check your credentials.")
    print(f"Status code: {e.status_code}")  # 401

ForbiddenError (403)

Raised when the API key is valid but doesn’t have permission to access the resource.

from elevenlabs import ElevenLabs, ForbiddenError

client = ElevenLabs(api_key="YOUR_API_KEY")

try:
    # Attempting to access a premium feature without subscription
    result = client.some_premium_feature()
except ForbiddenError as e:
    print("Access denied. Upgrade your plan to use this feature.")
    print(f"Status code: {e.status_code}")  # 403

NotFoundError (404)

Raised when the requested resource doesn’t exist.

from elevenlabs import ElevenLabs, NotFoundError

client = ElevenLabs(api_key="YOUR_API_KEY")

try:
    dictionary = client.pronunciation_dictionaries.get(
        pronunciation_dictionary_id="nonexistent_id"
    )
except NotFoundError as e:
    print("Pronunciation dictionary not found.")
    print(f"Status code: {e.status_code}")  # 404

TooEarlyError (425)

Raised when a request is made too early, typically when a resource is not yet ready.

from elevenlabs import ElevenLabs, TooEarlyError
import time

client = ElevenLabs(api_key="YOUR_API_KEY")

try:
    result = client.some_resource.get(resource_id="id")
except TooEarlyError as e:
    print("Resource not ready yet. Retrying...")
    time.sleep(5)
    # Retry logic here

ConflictError (409)

Raised when there’s a conflict with the current state of the resource.

from elevenlabs import ElevenLabs, ConflictError

client = ElevenLabs(api_key="YOUR_API_KEY")

try:
    # Attempting to create a resource that already exists
    voice = client.voices.ivc.create(
        name="Existing Voice Name",
        files=["sample.mp3"]
    )
except ConflictError as e:
    print("A voice with this name already exists.")
    print(f"Status code: {e.status_code}")  # 409

UnprocessableEntityError (422)

Raised when the request is well-formed but contains semantic errors.

from elevenlabs import ElevenLabs, UnprocessableEntityError

client = ElevenLabs(api_key="YOUR_API_KEY")

try:
    audio = client.text_to_speech.convert(
        text="Test",
        voice_id="valid_id",
        model_id="invalid_model"  # Valid format but doesn't exist
    )
except UnprocessableEntityError as e:
    print("The model ID is not valid or not available.")
    print(f"Status code: {e.status_code}")  # 422

Comprehensive Error Handling

Basic Pattern

Handle all possible errors in a single try-except block:

from elevenlabs import (
    ElevenLabs,
    BadRequestError,
    UnauthorizedError,
    ForbiddenError,
    NotFoundError,
    UnprocessableEntityError,
    ConflictError,
    TooEarlyError
)

client = ElevenLabs(api_key="YOUR_API_KEY")

try:
    audio = client.text_to_speech.convert(
        text="Hello world",
        voice_id="JBFqnCBsd6RMkjVDRZzb",
        model_id="eleven_multilingual_v2"
    )
    with open("output.mp3", "wb") as f:
        f.write(audio)
except BadRequestError as e:
    print(f"Invalid request parameters: {e.body}")
except UnauthorizedError:
    print("Authentication failed. Check your API key.")
except ForbiddenError:
    print("You don't have permission to access this resource.")
except NotFoundError:
    print("The requested resource was not found.")
except UnprocessableEntityError as e:
    print(f"Request validation failed: {e.body}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

Async Error Handling

Error handling works the same way with the async client:

import asyncio
from elevenlabs import AsyncElevenLabs, BadRequestError, UnauthorizedError

client = AsyncElevenLabs(api_key="YOUR_API_KEY")

async def generate_speech():
    try:
        audio = await client.text_to_speech.convert(
            text="Hello world",
            voice_id="JBFqnCBsd6RMkjVDRZzb",
            model_id="eleven_multilingual_v2"
        )
        return audio
    except BadRequestError as e:
        print(f"Bad request: {e.body}")
        raise
    except UnauthorizedError:
        print("Authentication failed")
        raise

asyncio.run(generate_speech())

Retry Logic

Implement retry logic for transient errors:

import time
from elevenlabs import ElevenLabs, TooEarlyError

def generate_with_retry(client, max_retries=3, delay=2):
    for attempt in range(max_retries):
        try:
            audio = client.text_to_speech.convert(
                text="Hello world",
                voice_id="JBFqnCBsd6RMkjVDRZzb",
                model_id="eleven_multilingual_v2"
            )
            return audio
        except TooEarlyError:
            if attempt < max_retries - 1:
                print(f"Attempt {attempt + 1} failed. Retrying in {delay}s...")
                time.sleep(delay)
                delay *= 2  # Exponential backoff
            else:
                print("Max retries reached")
                raise

client = ElevenLabs(api_key="YOUR_API_KEY")
audio = generate_with_retry(client)

Error Information

All error objects provide useful debugging information:

status_code · int

The HTTP status code of the error.

body · Any

The response body containing error details. For BadRequestError, this is a BadRequestErrorBody object with an error field.

headers · Dict[str, str]

The response headers, if any.

Accessing Error Details

from elevenlabs import ElevenLabs, BadRequestError

client = ElevenLabs(api_key="YOUR_API_KEY")

try:
    audio = client.text_to_speech.convert(
        text="",
        voice_id="invalid",
        model_id="eleven_multilingual_v2"
    )
except BadRequestError as e:
    print(f"Status Code: {e.status_code}")
    print(f"Error Message: {e.body.error}")
    if e.headers:
        print(f"Response Headers: {e.headers}")

Webhook Error Handling

Webhook signature verification can also raise errors:

from elevenlabs import ElevenLabs, BadRequestError

client = ElevenLabs(api_key="YOUR_API_KEY")

try:
    event = client.webhooks.construct_event(
        rawBody=request_body,
        sig_header=signature_header,
        secret="your_webhook_secret"
    )
except BadRequestError as e:
    # Invalid signature or timestamp
    print(f"Webhook verification failed: {e.body.error}")
    # Return 400 to the webhook sender
    return {"error": "Invalid signature"}, 400

Common webhook errors:

• "Missing signature header" - The signature header was not provided
• "Webhook secret not configured" - No secret was provided
• "No signature hash found with expected scheme v0" - Invalid signature format
• "Timestamp outside the tolerance zone" - Webhook is too old (>30 minutes)
• "Signature hash does not match" - Signature verification failed

Best Practices

Always validate input

Validate parameters before making API calls to avoid BadRequestError.

Use specific exceptions

Catch specific exception types rather than generic Exception when possible.

Log error details

Always log the full error information for debugging.

Implement retry logic

For transient errors like TooEarlyError, implement exponential backoff.

Never expose raw API errors to end users. Always catch exceptions and provide user-friendly error messages.

Next Steps

Async Client

Learn about async error handling patterns

Webhooks

Understand webhook-specific error handling