Fehler

API-Fehler

ElevenLabs verwendet standardmäßige HTTP-Statuscodes, um den Erfolg oder Fehler einer Anfrage anzuzeigen. Zusätzlich geben alle API-Anfragen ein JSON-Objekt mit einer detail-Eigenschaft zurück, die Informationen über den Fehler enthält.

Im Allgemeinen weist ein HTTP-Statuscode 200 auf eine erfolgreiche Anfrage hin. Ein 4xx-Code weist auf ein Problem mit der Anfrage hin, etwa einen ungültigen Parameter oder ein fehlendes Pflichtfeld. Ein HTTP-Statuscode 500 weist auf ein Problem mit den Servern von ElevenLabs hin, was selten vorkommen sollte.

Fehlereigenschaften

Beispiel für eine Fehlerantwort

Hier ist die Antwort für eine API-Anfrage, die eine falsche Modell-ID verwendet hat:

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

Anhand der Fehlereigenschaften sehen wir, dass es sich um einen Validierungsfehler handelt und der Code invalid_parameters lautet. Die Meldung enthält weitere Details zum Fehler, und die request_id ist eine eindeutige Kennung für die Anfrage, die zur Fehlerbehebung verwendet werden kann. Die Eigenschaft param zeigt den Parameter an, der den Fehler verursacht hat.

Fehlerbehandlung im SDK

Die ElevenLabs SDKs bieten typisierte Fehlerklassen, die Ihnen Zugriff auf die Fehlerdetails geben.

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

Ratenbegrenzung und Parallelität

Wenn Sie einen HTTP-Statuscode 429 erhalten, haben Sie entweder in kurzer Zeit zu viele Anfragen gestellt und das Ratenlimit für den API-Endpunkt überschritten oder das Parallelitätslimit für den API-Endpunkt überschritten. Der Fehler-code lautet entsprechend rate_limit_exceeded oder concurrent_limit_exceeded.

Bei einer Ratenbegrenzung sollten Sie bei einem 429-Fehler in Ihrem Code exponentielles Backoff implementieren. Das bedeutet, vor dem erneuten Versuch der Anfrage eine Verzögerung hinzuzufügen.

Bei Parallelität sollten Sie warten, bis die aktuellen Anfragen abgeschlossen sind, bevor Sie neue stellen. Weitere Informationen finden Sie im Abschnitt Parallelität und Priorität.

Fehlertypen

Ein Fehler enthält eine type-Eigenschaft, die den aufgetretenen Fehlertyp angibt. Mögliche Werte finden Sie in der Tabelle unten.

Fehlercodes