일관된 예외 처리: Exception Mapping

일관된 예외 처리: Exception Mapping

LLM을 여러 프로바이더에 붙이고 나면, 어떤 건 400을 주고 어떤 건 429나 503을 주는 식으로 에러가 제각각이라 예외 처리 코드를 프로바이더마다 따로 짜야 하는 일이 생겨요. LiteLLM은 이걸 깔끔하게 해결합니다. 모든 프로바이더의 예외를 OpenAI 예외 타입으로 매핑해 주거든요. 그래서 기존 OpenAI용 예외 핸들링이 그대로 동작해요.

출처: 공식문서 - Exception Mapping

전부 OpenAI 호환 예외로

LiteLLM의 모든 예외는 litellm에서 바로 import 할 수 있어요. 예를 들면 from litellm import BadRequestError처럼요. 각 예외는 OpenAI SDK의 예외 타입을 상속합니다.

대표적인 예외 매핑을 보면 이렇게 돼요.

만약 매핑되지 않은 오류가 오면 기본으로 APIConnectionError를 반환해요. 프로바이더가 500대 상태 코드를 반환하면 InternalServerError가 올라옵니다.

예외가 담는 추가 정보

모든 예외는 OpenAI 원본 예외를 상속하면서도 세 가지 추가 속성을 더 가집니다.

• status_code — 예외의 HTTP 상태 코드
• message — 에러 메시지
• llm_provider — 예외를 발생시킨 프로바이더

또한 LiteLLM 예외는 provider_specific_fields 속성을 포함해 프로바이더별 추가 오류 정보를 담습니다. 특히 Azure OpenAI는 상세한 콘텐츠 필터링 정보를 제공하는데, 이는 innererror 필드로 접근할 수 있어요.

왜 이런 매핑이 편한가

일관된 예외 타입 덕분에, 여러 프로바이더를 오가는 코드에서 예외 처리 로직을 한 번만 짜면 됩니다. 예를 들어 타임아웃이 나면 openai.APITimeoutError로 잡히므로, 이미 OpenAI용으로 작성한 except openai.APITimeoutError 블록이 Anthropic이든 Bedrock이든 그대로 동작해요.

import litellm
import openai

try:
    response = litellm.completion(
        model="gpt-4",
        messages=[{"role": "user", "content": "hello, write a 20 page essay"}],
        timeout=0.01,  # 이 설정 때문에 타임아웃 예외 발생
    )
except openai.APITimeoutError as e:
    print("Raised openai.APITimeoutError:", e)
    # e.status_code, e.message, e.llm_provider 사용 가능

예외가 지원되는 프로바이더 목록/경우는 프로바이더마다 다르므로, 실제로 어떤 예외가 어떤 프로바이더에서 발생할 수 있는지는 공식 문서의 예외 매핑 표를 확인하는 게 정확해요.

더 알아보기

• 모든 프로바이더 예외를 통일해 준다는 점은 LiteLLM이 "하나의 인터페이스"를 만드는 전체 개념과 이어져요. LiteLLM 개요를 참고하세요.
• 폴백/재시도와 결합되면 컨텍스트 초과·정책 위반 같은 예외를 감지해 자동으로 다른 모델로 넘기는 흐름을 만들 수 있어요. Router 문서에서 이어집니다.