Błędy

Błędy API

ElevenLabs używa standardowych kodów stanu HTTP, aby wskazać powodzenie lub niepowodzenie żądania. Dodatkowo wszystkie żądania API zwracają obiekt JSON z właściwością detail, która zawiera informacje o błędzie.

Zwykle kod stanu HTTP 200 oznacza udane żądanie. Kod 4xx wskazuje problem z żądaniem, np. nieprawidłowy parametr lub brak wymaganego pola. Kod stanu HTTP 500 wskazuje problem z serwerami ElevenLabs, co powinno zdarzać się rzadko.

Właściwości błędu

Przykładowa odpowiedź z błędem

Oto odpowiedź na żądanie API, w którym użyto nieprawidłowego identyfikatora modelu:

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

Na podstawie właściwości błędu widzimy, że jest to błąd walidacji, a kod to invalid_parameters. Komunikat zawiera więcej szczegółów, a request_id to unikalny identyfikator żądania, który możesz wykorzystać do diagnozy błędu. Właściwość param wskazuje parametr, który spowodował błąd.

Obsługa błędów SDK

SDK ElevenLabs udostępniają typowane klasy błędów, które dają dostęp do szczegółów błędu.

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

Limity żądań i współbieżność

Jeśli otrzymasz kod stanu HTTP 429, oznacza to, że w krótkim czasie wysłano zbyt wiele żądań i przekroczono limit żądań dla endpointu API albo przekroczono limit współbieżności dla tego endpointu. Odpowiedni code błędu to rate_limit_exceeded lub concurrent_limit_exceeded.

W przypadku limitu żądań zaimplementuj w kodzie exponential backoff po otrzymaniu błędu 429. Oznacza to dodanie opóźnienia przed ponowną próbą wysłania żądania.

W przypadku współbieżności poczekaj, aż bieżące żądania się zakończą, zanim wyślesz kolejne. Więcej informacji znajdziesz w sekcji Współbieżność i priorytet.

Typy błędów

Błąd ma właściwość type, która wskazuje jego typ. Możliwe wartości znajdziesz w tabeli poniżej.

Kody błędów