Erreurs

Erreurs d’API

ElevenLabs utilise des codes d’état HTTP standard pour indiquer si une requête a réussi ou échoué. De plus, toutes les requêtes API renvoient un objet JSON doté d’une propriété detail qui contient des informations sur l’erreur.

En règle générale, un code d’état HTTP 200 indique qu’une requête a réussi. Un code 4xx indique un problème dans la requête, comme un paramètre non valide ou un champ obligatoire manquant. Un code d’état HTTP 500 indique un problème sur les serveurs d’ElevenLabs, ce qui devrait être rare.

Propriétés des erreurs

Exemple de réponse d’erreur

Voici la réponse d’une requête API ayant utilisé un ID de modèle incorrect :

{
  "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"
  }
}

Les propriétés de l’erreur indiquent qu’il s’agit d’une erreur de validation et que son code est invalid_parameters. Le message fournit davantage de détails, tandis que request_id est un identifiant unique de la requête permettant de résoudre le problème. La propriété param indique le paramètre à l’origine de l’erreur.

Gestion des erreurs dans les SDK

Les SDK ElevenLabs fournissent des classes d’erreur typées qui vous donnent accès aux détails de l’erreur.

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

Limitation de débit et requêtes simultanées

Si vous recevez un code d’état HTTP 429, cela signifie que vous avez soit effectué trop de requêtes sur une courte période et dépassé la limite de débit de l’endpoint API, soit dépassé la limite de requêtes simultanées de cet endpoint. Le code de l’erreur sera respectivement rate_limit_exceeded ou concurrent_limit_exceeded.

En cas de limitation de débit, implémentez un backoff exponentiel dans votre code lorsqu’une erreur 429 est reçue. Cela consiste à ajouter un délai avant de réessayer la requête.

En cas de limite de requêtes simultanées, attendez que les requêtes en cours soient terminées avant d’en effectuer de nouvelles. Consultez la section Requêtes simultanées et priorité pour en savoir plus.

Types d’erreur

Une erreur comporte une propriété type indiquant le type d’erreur survenue. Consultez le tableau ci-dessous pour connaître les valeurs possibles.

Codes d’erreur