Erros

Erros da API

A ElevenLabs usa códigos de status HTTP padrão para indicar o sucesso ou a falha de uma solicitação. Além disso, todas as solicitações à API retornam um objeto JSON com uma propriedade detail que contém informações sobre o erro.

Em geral, um código de status HTTP 200 indica uma solicitação bem-sucedida. Um código 4xx indica um problema com a solicitação, como um parâmetro inválido ou um campo obrigatório ausente. Um código de status HTTP 500 indica um problema nos servidores da ElevenLabs, o que deve ser raro.

Propriedades do erro

Exemplo de resposta de erro

Esta é a resposta para uma solicitação à API que usou um ID de modelo incorreto:

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

Usando as propriedades do erro, podemos ver que se trata de um erro de validação e que o código é invalid_parameters. A mensagem fornece mais detalhes sobre o erro, e o request_id é um identificador exclusivo da solicitação que pode ser usado para solucionar o erro. A propriedade param indica o parâmetro que causou o erro.

Tratamento de erros no SDK

Os SDKs da ElevenLabs oferecem classes de erro tipadas que dão acesso aos detalhes do erro.

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

Limite de taxa e simultaneidade

Se você receber um código de status HTTP 429, isso significa que fez muitas solicitações em um curto período e excedeu o limite de taxa do endpoint da API, ou que excedeu o limite de simultaneidade do endpoint da API. O code do erro será rate_limit_exceeded ou concurrent_limit_exceeded, respectivamente.

No caso de limite de taxa, você deve implementar backoff exponencial no código ao receber um erro 429. Isso significa adicionar um atraso antes de tentar a solicitação novamente.

No caso de simultaneidade, você deve aguardar a conclusão das solicitações atuais antes de fazer novas. Consulte a seção Simultaneidade e prioridade para mais informações.

Tipos de erro

Um erro vem com uma propriedade type que indica o tipo de erro ocorrido. Consulte a tabela abaixo para ver os valores possíveis.

Códigos de erro