Errori

Errori API

ElevenLabs utilizza codici di stato HTTP standard per indicare l’esito positivo o negativo di una richiesta. Inoltre, tutte le richieste API restituiscono un oggetto JSON con una proprietà detail contenente informazioni sull’errore.

In generale, un codice di stato HTTP 200 indica che la richiesta è stata completata correttamente. Un codice 4xx indica un problema con la richiesta, ad esempio un parametro non valido o un campo obbligatorio mancante. Un codice di stato HTTP 500 indica un problema con i server di ElevenLabs, che dovrebbe verificarsi raramente.

Proprietà dell’errore

Esempio di risposta di errore

Ecco la risposta a una richiesta API che ha utilizzato un ID modello errato:

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

Dalle proprietà dell’errore, possiamo vedere che si tratta di un errore di convalida e che il codice è invalid_parameters. Il messaggio fornisce maggiori dettagli sull’errore e request_id è un identificatore univoco della richiesta che può essere usato per risolvere il problema. La proprietà param indica il parametro che ha causato l’errore.

Gestione degli errori negli SDK

Gli SDK di ElevenLabs forniscono classi di errore tipizzate che ti consentono di accedere ai dettagli dell’errore.

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

Limitazione della frequenza e concorrenza

Se ricevi un codice di stato HTTP 429, significa che hai effettuato troppe richieste in un breve periodo e hai superato il limite di frequenza per l’endpoint API, oppure hai superato il limite di concorrenza per l’endpoint API. Il code dell’errore sarà rispettivamente rate_limit_exceeded o concurrent_limit_exceeded.

In caso di limitazione della frequenza, dovresti implementare un backoff esponenziale nel codice quando ricevi un errore 429. Ciò significa aggiungere un ritardo prima di riprovare la richiesta.

In caso di concorrenza, dovresti attendere il completamento delle richieste correnti prima di effettuarne di nuove. Per maggiori informazioni, consulta la sezione Concorrenza e priorità.

Tipi di errore

Un errore include una proprietà type che indica il tipo di errore verificatosi. Consulta la tabella seguente per i valori possibili.

Codici di errore