AI SDK Errors

AI SDK는 오류 메시지 문자열을 매칭하지 않고도 애플리케이션이 예상되는 실패 모드를 처리할 수 있도록 **타입화된 오류(typed errors)**를 제공해요. 오류 이름(예: APICallError)만으로 예외를 잡을 수 있으니, 문자열 매칭에 의존하지 않아도 되고 다양한 오류를 정밀하게 구분할 수 있답니다.

출처: 문서

본문

AI SDK는 오류 메시지 문자열을 매칭하지 않고도 애플리케이션이 예상되는 실패 모드를 처리할 수 있도록 타입화된 오류를 제공합니다.

오류 임포트하기 (Importing Errors)

애플리케이션 패키지 이름은 @ai-sdk/ai가 아니라 ai입니다. 이 패키지는 @ai-sdk/provider의 공통 프로바이더 수준 오류를, AI SDK Core가 발생시키는 더 높은 수준의 오류와 함께 다시 내보냅니다:

import { APICallError, NoObjectGeneratedError } from 'ai';

@ai-sdk/provider에 직접 의존하는 프로바이더 구현은 그 패키지에서 프로바이더 수준 오류를 임포트할 수 있습니다:

import { APICallError, InvalidResponseDataError } from '@ai-sdk/provider';

타입화된 오류 처리로 마이그레이션 (Migrating to Typed Error Handling)

메시지 매칭이나 무조건적인 제네릭 catch 블록을, 사용 가능한 가장 구체적인 정적 isInstance 가드로 대체하세요. AI SDK 오류의 폴백이 필요할 때 AISDKError를 마지막에 확인하세요:

import { AISDKError, APICallError, generateText } from 'ai';

try {
  await generateText({
    model,
    prompt: 'Write a vegetarian lasagna recipe for 4 people.',
  });
} catch (error) {
  if (APICallError.isInstance(error)) {
    console.error('Provider request failed:', error.statusCode);
    return;
  }

  if (AISDKError.isInstance(error)) {
    console.error('AI SDK error:', error.name);
    return;
  }

  throw error;
}

클래스가 제공한다면 error instanceof ErrorClass보다 ErrorClass.isInstance(error)를 선호하세요. 정적 가드는 여러 버전의 AI SDK 패키지가 로드된 경우에도 작동합니다.

일반적인 실패 모드 (Common Failure Modes)

실패 모드	확인할 오류
네트워크 오류 또는 비성공 응답 때문에 프로바이더 요청이 실패	`APICallError`
자동 재시도가 소진됨	`RetryError`
응답 스트림이 시작된 후 프로바이더가 오류를 보고함	`StreamProviderError`
구조화된 출력을 파싱하거나 검증할 수 없음	`NoObjectGeneratedError`; `cause`에서 `JSONParseError` 또는 `TypeValidationError`를 확인하세요
생성 호출이 사용 가능한 출력을 반환하지 않음	`NoOutputGeneratedError` 또는 모달리티별 `No*GeneratedError`
모델이 누락된 도구를 호출하거나 잘못된 도구 입력을 제공함	`NoSuchToolError` 또는 `InvalidToolInputError`
도구 호출 복구가 실패함	`ToolCallRepairError`
응답이 강제된 `toolChoice`를 위반함	`ToolChoiceViolationError`
메시지 기록에 해결되지 않은 도구 호출 또는 잘못된 승인이 포함됨	`MissingToolResultsError`, `InvalidToolApprovalError`, 또는 `InvalidToolApprovalSignatureError`
프로바이더 또는 모델을 해석할 수 없음	`NoSuchProviderError`, `NoSuchModelError`, 또는 `NoSuchProviderReferenceError`
프로바이더 응답이 비어 있거나, 잘못되었거나, 유효하지 않음	`EmptyResponseBodyError`, `JSONParseError`, 또는 `InvalidResponseDataError`
요청한 모델 또는 프로바이더가 기능 또는 사양 버전을 지원하지 않음	`UnsupportedFunctionalityError` 또는 `UnsupportedModelVersionError`
UI 메시지를 변환할 수 없거나 UI 메시지 스트림이 유효하지 않음	`MessageConversionError` 또는 `UIMessageStreamError`

오류 참조 (Error Reference)

기본 오류 (Base Error)

AISDKError: AI SDK 오류의 기본 클래스이자 광범위한 타입 가드.

AI SDK Errors

AI SDK Errors

본문

오류 임포트하기 (Importing Errors)

타입화된 오류 처리로 마이그레이션 (Migrating to Typed Error Handling)

일반적인 실패 모드 (Common Failure Modes)

오류 참조 (Error Reference)

기본 오류 (Base Error)

프로바이더 요청 및 응답 (Provider Requests and Responses)

입력 및 메시지 스트림 (Inputs and Message Streams)

생성된 출력 (Generated Output)

프로바이더 및 모델 호환성 (Providers and Model Compatibility)

도구 및 승인 (Tools and Approvals)

더 알아보기 (Learn more)