Errors

API errors

ElevenLabs uses standard HTTP status codes to indicate the success or failure of a request. Additionally, all API requests return a JSON object with a detail property that contains information about the error.

In general, a 200 HTTP status code indicates a successful request. A 4xx code indicates a problem with the request, like an invalid parameter or missing required field. A 500 HTTP status code indicates a problem with ElevenLabs’ servers, which should be rare.

Error properties

Example error response

Here’s the response for an API request that used an incorrect model ID:

1
{
2
  "detail": {
3
    "type": "validation_error",
4
    "code": "invalid_parameters",
5
    "message": "The 'keyterms' parameter is only supported with the 'scribe_v2' model. You specified 'scribe_v1'.",
6
    "status": "invalid_parameters",
7
    "request_id": "3c807fc4c3a1705f9638ecc764a91c01",
8
    "param": "keyterms"
9
  }
10
}

Using the error properties, we can see that the error is a validation error, and the code is invalid_parameters. The message provides more details about the error, and the request_id is a unique identifier for the request that can be used to troubleshoot the error. The param property indicates the parameter that caused the error.

SDK error handling

The ElevenLabs SDKs provide typed error classes that give you access to the error details.

1
from elevenlabs import ElevenLabs, ApiError
2
3
elevenlabs = ElevenLabs()
4
5
try:
6
    audio = elevenlabs.text_to_speech.convert(
7
        voice_id="invalid-voice-id",
8
        model_id="eleven_v3",
9
        text="Hello, world!",
10
    )
11
except ApiError as e:
12
    print(f"Status code: {e.status_code}")
13
14
    # Access the error body
15
    if e.body and "detail" in e.body:
16
        detail = e.body["detail"]
17
        print(f"Error type: {detail.get('type')}")
18
        print(f"Error code: {detail.get('code')}")
19
        print(f"Message: {detail.get('message')}")
20
        print(f"Request ID: {detail.get('request_id')}")
21
22
        # Handle specific error types
23
        if detail.get("type") == "rate_limit_error":
24
            print("Rate limited - implement exponential backoff")
25
        elif detail.get("type") == "authentication_error":
26
            print("Check your API key")

Rate limiting and concurrency

If you receive a 429 HTTP status code, it means you have either made too many requests in a short period of time and exceeded the rate limit for the API endpoint, or you have exceeded the concurrency limit for the API endpoint. The error code will be rate_limit_exceeded or concurrent_limit_exceeded respectively.

In the case of rate limiting, you should implement exponential backoff in your code when a 429 error is received. This means adding a delay before retrying the request.

In the case of concurrency, you should wait for the current requests to complete before making new ones. See the Concurrency and priority section for more information.

Error types

An error comes with a type property that indicates the type of error that occurred. See the table below for possible values.

Error codes