Errores

Errores de la API

ElevenLabs utiliza códigos de estado HTTP estándar para indicar si una solicitud se ha realizado correctamente o ha fallado. Además, todas las solicitudes a la API devuelven un objeto JSON con una propiedad detail que contiene información sobre el error.

En general, un código de estado HTTP 200 indica que la solicitud se ha realizado correctamente. Un código 4xx indica un problema con la solicitud, como un parámetro no válido o la falta de un campo obligatorio. Un código de estado HTTP 500 indica un problema con los servidores de ElevenLabs, algo que debería ocurrir rara vez.

Propiedades de los errores

Ejemplo de respuesta de error

Esta es la respuesta de una solicitud a la API que ha utilizado un ID de modelo incorrecto:

{
  "detail": {
    "type": "validation_error",
    "code": "invalid_parameters",
    "message": "The 'keyterms' parameter is only supported with the 'scribe_v2' model. You specified 'scribe_v1'.",
    "status": "invalid_parameters",
    "request_id": "3c807fc4c3a1705f9638ecc764a91c01",
    "param": "keyterms"
  }
}

Con las propiedades del error, podemos ver que se trata de un error de validación y que el código es invalid_parameters. El mensaje ofrece más detalles sobre el error y request_id es un identificador único de la solicitud que puede utilizarse para solucionar el error. La propiedad param indica el parámetro que ha causado el error.

Gestión de errores en los SDK

Los SDK de ElevenLabs proporcionan clases de error tipadas que te dan acceso a los detalles del error.

from elevenlabs import ElevenLabs
from elevenlabs.core import ApiError
elevenlabs = ElevenLabs()
try:
    audio = elevenlabs.text_to_speech.convert(
        voice_id="invalid-voice-id",
        model_id="eleven_v4",
        text="Hello, world!",
    )
except ApiError as e:
    print(f"Status code: {e.status_code}")
    # Access the error body
    if e.body and "detail" in e.body:
        detail = e.body["detail"]
        print(f"Error type: {detail.get('type')}")
        print(f"Error code: {detail.get('code')}")
        print(f"Message: {detail.get('message')}")
        print(f"Request ID: {detail.get('request_id')}")
        # Handle specific error types
        if detail.get("type") == "rate_limit_error":
            print("Rate limited - implement exponential backoff")
        elif detail.get("type") == "authentication_error":
            print("Check your API key")

Límite de solicitudes y concurrencia

Si recibes un código de estado HTTP 429, significa que has realizado demasiadas solicitudes en poco tiempo y has superado el límite de solicitudes de la ruta de API, o que has superado el límite de concurrencia de la ruta de API. El code de error será rate_limit_exceeded o concurrent_limit_exceeded, respectivamente.

En caso de límite de solicitudes, debes implementar un retroceso exponencial en tu código cuando recibas un error 429. Esto implica añadir una espera antes de volver a intentar la solicitud.

En caso de concurrencia, debes esperar a que terminen las solicitudes actuales antes de hacer otras nuevas. Consulta la sección Concurrencia y prioridad para obtener más información.

Tipos de error

Un error incluye una propiedad type que indica el tipo de error que se ha producido. Consulta la tabla siguiente para ver los posibles valores.

Códigos de error