model_not_found / 404 — Claude, Gemini 및 게이트웨이의 모델 명명

모델 ID는 이식되지 않습니다. api.anthropic.com은 날짜가 포함된 ID를, Gemini는 자체 버전 문자열을, 각 게이트웨이는 슬러그를 요구합니다. 여기서 404는 “이 호스트에는 정확히 이 문자열의 모델이 없음”을 뜻합니다. 해결책은 항상 엔드포인트에 제공 항목을 직접 묻는 것입니다.

오류

응답(HTTP 404)

{
  "error": {
    "type": "model_not_found",
    "message": "The model 'claude-sonnet' does not exist or you do not have access to it.",
    "code": "model_not_found"
  }
}

원인과 해결 방법 한눈에 보기

원인	해결 방법
다른 호스트에서 가져온 모델 ID	각 API에는 자체 네임스페이스가 있습니다. 블로그 게시물이 아니라 엔드포인트 자체의 모델 목록에서 ID를 복사하세요.
사용 중단/이름 변경된 버전	제공업체는 날짜가 포함된 스냅샷을 폐기합니다. 현재 ID를 고정하고 사용 중단 공지를 구독하세요.
오타가 있거나 잘린 슬러그	claude-sonnet은 어디에도 존재하는 모델이 아닙니다. 정확한 문자열이 중요합니다.
모델은 존재하지만 키/요금제에서 비활성화됨	일부 호스트는 요금제에 따라 모델을 제한합니다. 목록 엔드포인트에는 YOUR 키가 호출할 수 있는 항목이 표시됩니다.

호출 중인 엔드포인트에서 모델 나열

GET /v1/models는 모든 OpenAI 호환 호스트에서 기준이 되는 정보입니다. 키가 사용할 수 있는 정확한 ID를 반환합니다:

list-models.sh

curl -s https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer $KUNAVO_API_KEY" \
  | python3 -c "import json,sys; print('\n'.join(m['id'] for m in json.load(sys.stdin)['data']))"

하드코딩하지 말고 런타임에 모델 확인

카탈로그는 변경됩니다(새 스냅샷, 폐기). 시작 시 모델 목록을 확인하고, 구성된 슬러그를 우선하되 대체 항목을 두며, 구성된 슬러그가 /v1/models에서 사라지면 프로덕션에서 404가 발생하기 전에 알림을 보내세요.

Kunavo를 통해 호출하는 경우

Kunavo는 GET /v1/models에 모델별 메타데이터와 함께 나열되는 안정적인 사람이 읽을 수 있는 슬러그(claude-sonnet-5, gpt-5-6-terra, claude-fable-5)를 사용합니다. 폐기된 슬러그는 사이트의 모델 페이지에서 후속 모델로 301 리디렉션되므로 링크가 끊어지지 않습니다. 목록 엔드포인트가 권위 있는 기준이며, 이를 읽는 에이전트에게 llms.txt도 같은 내용을 말합니다.

자주 묻는 질문

같은 모델 ID가 한 API에서는 작동하고 다른 API에서는 404가 되는 이유는 무엇인가요?

ID는 호스트별로 네임스페이스가 다르기 때문입니다. Anthropic의 날짜가 포함된 ID, Gemini의 버전 이름, 각 게이트웨이의 슬러그는 관련 모델을 가리키더라도 모두 다른 문자열입니다. 항상 대상 엔드포인트 자체의 모델 목록에서 복사하세요.

모델 폐기에 대비하려면 어떻게 해야 하나요?

시작 시 /v1/models를 확인하고, 모델 ID를 코드가 아닌 구성에 두며, 대체 체인을 정의하고, 구성된 ID가 사라지면 알림을 보내세요. 그러면 프로덕션 404를 구성 변경으로 바꿀 수 있습니다.