오류

API 오류

ElevenLabs는 요청의 성공 또는 실패를 나타내기 위해 표준 HTTP 상태 코드를 사용합니다. 또한 모든 API 요청은 오류 정보를 포함하는 detail 속성이 있는 JSON 객체를 반환합니다.

일반적으로 200 HTTP 상태 코드는 요청이 성공했음을 나타냅니다. 4xx 코드는 잘못된 매개변수나 필수 필드 누락 등 요청에 문제가 있음을 나타냅니다. 500 HTTP 상태 코드는 ElevenLabs 서버에 문제가 있음을 나타내며, 이는 드물게 발생합니다.

오류 속성

오류 응답 예시

잘못된 모델 ID를 사용한 API 요청의 응답은 다음과 같습니다.

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

오류 속성을 통해 이 오류가 유효성 검사 오류이고 코드가 invalid_parameters임을 알 수 있습니다. 메시지는 오류에 관한 자세한 정보를 제공하며, request_id는 오류 해결에 사용할 수 있는 요청의 고유 식별자입니다. param 속성은 오류를 일으킨 매개변수를 나타냅니다.

SDK 오류 처리

ElevenLabs SDK는 오류 세부 정보에 액세스할 수 있는 타입 지정 오류 클래스를 제공합니다.

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

속도 제한 및 동시성

429 HTTP 상태 코드를 받았다면 짧은 시간 안에 너무 많은 요청을 보내 API 엔드포인트의 속도 제한을 초과했거나, API 엔드포인트의 동시성 제한을 초과했다는 의미입니다. 오류 code는 각각 rate_limit_exceeded 또는 concurrent_limit_exceeded입니다.

속도 제한의 경우 429 오류를 받았을 때 코드에 지수 백오프를 구현해야 합니다. 즉, 요청을 다시 시도하기 전에 지연 시간을 추가해야 합니다.

동시성의 경우 새 요청을 보내기 전에 현재 요청이 완료될 때까지 기다려야 합니다. 자세한 내용은 동시성 및 우선순위 섹션을 참고하세요.

오류 유형

오류에는 발생한 오류의 유형을 나타내는 type 속성이 포함됩니다. 가능한 값은 아래 표를 참고하세요.

오류 코드