Claude API model_not_found (not_found_error): 원인과 해결법

Claude API model_not_found not_found_error는 지정한 model 문자열이 존재하지 않거나 deprecated된 경우에 발생합니다 (2026 기준). 모델 이름 오류이며, 재시도하지 말고 요청 자체를 수정해야 합니다. 이 글은 5가지 흔한 원인과 Python/TypeScript 코드 예시를 다룹니다.

전반적인 Claude API 에러 처리 패턴은 Claude API Error Handling 가이드를 참고하세요.

무엇을 의미하는가?

model_not_found 에러 서브타입는 지정한 model 문자열이 존재하지 않거나 deprecated된 경우을 의미합니다. Anthropic API의 에러 응답 본문에는 error.type이 "not_found_error"로 명시되며, error.message에 구체적 사유가 옵니다.

응답 예시:

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "..."
  }
}

흔한 원인 5가지

1. 오타 (예: claude-sonnet-4 → 정답: claude-sonnet-4-5)
2. Deprecated 모델 사용 (claude-2.0, claude-instant-1.2)
3. Legacy 형식 (claude-sonnet-4-5-20240229) — 신형식 권장
4. Bedrock 사용 시 region에 미배포된 모델

해결 코드 (Python)

VALID_MODELS = {
    "claude-haiku-4-5", "claude-sonnet-4-5", "claude-opus-4-5",
    # Add aliases as Anthropic releases them
}

def validate_model(model: str):
    if model not in VALID_MODELS:
        raise ValueError(
            f"{model} not in valid set. Use one of: {VALID_MODELS}"
        )

해결 코드 (TypeScript)

const VALID_MODELS = new Set([
  "claude-haiku-4-5",
  "claude-sonnet-4-5",
  "claude-opus-4-5",
]);

function validateModel(model: string): void {
  if (!VALID_MODELS.has(model)) {
    throw new Error(`${model} invalid`);
  }
}

구버전 모델 마이그레이션 가이드

기존 코드에서 deprecated 모델 이름을 사용하고 있다면 다음 매핑으로 교체하세요:

코드베이스 전체 마이그레이션:

# 구버전 모델 이름을 일괄 검색
grep -r "claude-2\|claude-3\|claude-instant" ./src --include="*.py" --include="*.ts"

# 발견된 파일에서 모델 이름을 상수로 분리한 뒤 중앙 관리

모델 이름을 코드 전체에 하드코딩하면 Anthropic이 새 모델을 출시할 때마다 여러 파일을 수정해야 합니다. MODEL_REGISTRY 딕셔너리나 환경변수(CLAUDE_MODEL=claude-sonnet-4-5)로 중앙 관리하면 한 곳만 수정하면 됩니다.

재시도하지 마세요

이 에러는 클라이언트 측 문제라 재시도해도 같은 결과입니다. 위 원인을 확인하고 요청을 수정한 뒤 재발송하세요.

비용 영향

이 에러는 요청이 처리되지 않았으므로 비용이 청구되지 않습니다. 단, 잘못된 모델로 요청을 반복하다가 다른 에러가 발생할 수 있으니 모니터링이 필요합니다.

자세한 비용 절감 패턴은 Claude API Cost and Prompt Caching Break-Even 또는 무료 비용 계산기를 참고하세요.

2026 Claude 모델 이름 레지스트리

다음 표는 2026년 기준 유효한 모델 이름 목록입니다. 이 외의 문자열은 model_not_found를 유발합니다:

자주 틀리는 이름 패턴:

• claude-sonnet-4 (틀림) → claude-sonnet-4-5 (정답)
• claude-3-5-sonnet (틀림, 구버전) → claude-sonnet-4-5 (신버전)
• claude-opus-4-5 (틀림) → claude-opus-4 (정답)
• claude-4-sonnet (틀림) → claude-sonnet-4-5 (정답)

빠른 진단 체크리스트

모델 이름 오류를 빠르게 찾는 체크리스트:

• 모델 이름이 위 레지스트리 테이블과 정확히 일치하는가?
• 코드에서 하드코딩된 모델 이름을 상수로 관리하고 있는가? (분산된 하드코딩 → 오타 위험)
• VALID_MODELS 세트에서 사전 검증 후 API를 호출하고 있는가?
• 구버전 모델(claude-2.0, claude-instant-1.2)에서 마이그레이션됐는가?
• AWS Bedrock 사용 시 모델 이름 대신 ARN(arn:aws:bedrock:...)을 사용하는가?

프로덕션 모니터링

모델 이름은 배포 시 고정되므로, 코드 배포 직후 모델 유효성을 사전 검증하는 패턴이 효과적입니다:

import anthropic, logging

logger = logging.getLogger("claude.model")

# 2026 유효 모델 집합 — 신규 모델 출시 시 업데이트
VALID_MODELS = {
    "claude-haiku-4-5",
    "claude-sonnet-4-5",
    "claude-opus-4",
    "claude-haiku-4-5-20250514",
    "claude-sonnet-4-5-20250514",
}

def safe_create(client: anthropic.Anthropic, model: str, **kwargs):
    if model not in VALID_MODELS:
        logger.error(
            "model_not_found — 배포 전 모델 이름 점검 필요",
            extra={
                "requested_model": model,
                "valid_models": list(VALID_MODELS),
            }
        )
        raise ValueError(
            f"'{model}'은 유효하지 않은 모델입니다. "
            f"사용 가능: {sorted(VALID_MODELS)}"
        )
    return client.messages.create(model=model, **kwargs)

언제 지원팀에 연락해야 하나요?

model_not_found는 항상 클라이언트 코드 수정으로 해결됩니다. 다음 경우에만 support.anthropic.com에 문의하세요:

• Anthropic 문서에 명시된 이름을 정확히 사용했는데 not_found_error가 반환되는 경우
• Bedrock에서 특정 리전에서만 모델을 찾지 못하는 경우 (리전 배포 확인 필요)
• 이전에 정상 동작하던 모델 이름이 갑자기 not_found를 반환하는 경우 (deprecated 가능성 → 공식 마이그레이션 가이드 요청)

관련 에러

• 400 invalid_request_error — 잘못된 요청 형식
• 401 authentication_error — 인증 실패
• 403 permission_error — 권한 부족
• 429 rate_limit_error — Rate limit 초과
• 529 overloaded_error — API 일시 과부하

자주 묻는 질문

model_not_found 에러가 떴을 때 비용이 청구되나요?

처리되지 않은 요청이므로 청구되지 않습니다. 단, 무한 재시도 루프는 다른 에러로 비용을 발생시킬 수 있습니다.

model_not_found와 다른 에러의 차이는?

model_not_found는 클라이언트 측 문제로 요청 수정 없이는 재시도해도 같은 결과입니다. 5xx 에러 (500/529)는 일시적 서버 이슈라 재시도가 효과적입니다.

Bedrock/Vertex에서도 같은 에러 코드인가요?

네, Anthropic의 error.type 명명 규칙은 모든 deployment (Direct API, AWS Bedrock, GCP Vertex AI)에서 동일합니다. 다만 HTTP 상태 코드는 platform 별로 wrapping되어 다를 수 있습니다 (예: Bedrock은 에러 type을 다른 prefix로 변경).

다음 단계

• 프로덕션 코드에 retry 로직을 추가하려면 Production Patterns for Claude Agents를
• 비용을 모니터링하려면 Claude API 비용 모니터링 가이드를
• 에러 분류 자동화는 무료 /cheatsheet-한국어에서 30개 프롬프트로

에러 처리 패턴 30개 + Pydantic 검증 코드 — Claude API Cost Optimization 마스터클래스 ($59)에 retry 미들웨어, 비용 가드레일, 에러 알림 패턴 12편 포함.