[나의 앱 개발기] 어느 날 갑자기 AI 앱이 먹통됐다: API 모델명 변경 404 에러 해결 후기

분명히 어제까지는 잘 됐습니다. 아무것도 건드린 게 없어요. 코드도 그대로, 서버도 그대로인데 갑자기 앱이 먹통이 됐습니다.

요청한 대상을 찾을 수 없다는 404 오류 화면 예시
404 오류는 요청한 대상을 서버에서 찾을 수 없다는 뜻입니다(웹사이트 404 화면 예시)
이미지 출처: Wikimedia Commons · Wikimedia Foundation · CC BY-SA 4.0

제가 만든 AI 학습 앱 aitestu.com에서 문제 생성 버튼을 누르면 이런 에러가 떴습니다.

API 오류 404: {"type":"error","error":{"type":"not_found_error","message":"model: claude-sonnet-4-20250514"},"request_id":"req_..."}

처음엔 뭔가 제가 실수로 코드를 건드린 줄 알았습니다. GitHub 커밋 이력을 하나씩 뒤졌고, Vercel 배포 로그도 뒤졌어요. 근데 아무것도 바뀐 게 없었습니다. 그러다 에러 메시지를 다시 자세히 읽었을 때 뭔가 걸렸습니다.

"model: claude-sonnet-4-20250514" — 이 모델을 찾을 수 없다는 거였습니다.


모델 지원 종료와 다른 모델로의 전환을 구분하기

Anthropic은 Claude 모델을 주기적으로 업데이트하고, 기존 모델의 지원 종료 일정도 공지합니다. 제가 코드에 넣었던 claude-sonnet-4-20250514의 지원 종료와 claude-sonnet-4-5로의 전환은 단순히 같은 모델의 이름이 바뀐 것과는 다릅니다.

아래 표는 제가 2026년 8월 당시 사용하던 ID와 교체한 ID를 정리한 것입니다. 모든 기존 ID가 사용 불가라는 뜻은 아닙니다. claude-haiku-4-5-20251001은 공식 지원 종료 안내에서 활성 상태이며, claude-haiku-4-5로 바꾼 것을 Haiku 모델의 지원 종료로 해석해서는 안 됩니다.

Anthropic의 Claude 웹사이트 화면
앱에서 호출하는 모델 ID와 지원 상태를 확인해야 합니다(Claude 웹사이트 화면)
이미지 출처: Wikimedia Commons · VulcanSphere · Public domain
당시 사용하던 모델 ID 작성자가 교체한 모델 ID
claude-sonnet-4-20250514 claude-sonnet-4-5
claude-haiku-4-5-20251001 claude-haiku-4-5

Sonnet 4에서 Sonnet 4.5로 옮기는 것은 다른 모델로 전환하는 것이고, Haiku 4.5의 날짜가 붙은 ID를 별칭으로 바꾸는 것은 같은 모델 계열의 ID 선택입니다. 날짜가 붙은 모델 ID가 모두 사라진 것은 아니므로, 실제 지원 상태는 공식 모델 목록과 지원 종료 안내를 확인해야 합니다.

해결 방법은 딱 한 줄

저는 Next.js로 만들었고, API 호출은 /api/generate/route.js 파일에 몰아놨습니다. 거기서 모델명만 바꾸면 끝이었어요.

1. route.js 에서 모델명 교체

파일 안에서 아래 두 줄을 찾아서 바꿨습니다.

- claude-sonnet-4-20250514
+ claude-sonnet-4-5

- claude-haiku-4-5-20251001
+ claude-haiku-4-5

2. GitHub push → Vercel 자동 배포

저장하고 push 한 번이면 끝입니다. Vercel이 자동으로 배포해주니까요. 수정하고 2분 만에 앱이 다시 정상 작동했습니다.

3. 모델명 확인하는 방법

앞으로 이런 일이 또 생길 수 있으니까, 모델명은 항상 Anthropic 공식 문서에서 확인하는 게 좋습니다.

Anthropic 모델 목록 문서에 들어가면 현재 사용 가능한 모델명 전체 목록이 나옵니다. 지원이 끝나는 모델은 모델 지원 종료(deprecations) 안내에 따로 정리되어 있습니다. API 에러가 나면 제일 먼저 여기서 모델명을 확인해보세요.


비개발자가 이런 에러를 만났을 때

저는 개발자가 아닙니다. Claude AI랑 같이 앱을 만든 직장인이에요. 그래서 이런 에러가 처음 떴을 때 진짜 당황했습니다. 코드를 다 갈아엎어야 하나 싶었거든요.

근데 에러 메시지를 차분히 읽어보는 것, 이게 핵심이더라고요. 에러 메시지는 항상 원인을 담고 있습니다. 영어라서 읽기 싫어도 그냥 Claude한테 에러 메시지 통째로 붙여넣고 "이게 무슨 에러야?" 라고 물어보면 바로 답이 나왔습니다.

모니터에 띄워진 코드 화면
에러 메시지는 영어라도 차분히 읽으면 원인이 담겨 있습니다(참고용 일반 사진)
이미지 출처: Wikimedia Commons · Sai Kiran Anagani · CC0

이번 에러 해결 과정을 정리하면 이렇습니다.

에러 메시지 복사
Claude한테 붙여넣기
원인 파악 → 모델명 한 줄 수정 → 해결!

총 걸린 시간이 15분이었습니다. 개발자였으면 1분이었겠지만, 비개발자도 충분히 혼자 해결할 수 있는 수준이에요.


왜 멀쩡하던 모델명이 갑자기 안 될까

AI 회사들은 새 모델을 내놓으면서 오래된 모델을 일정 기간이 지나면 지원 종료(deprecation, retirement) 처리합니다. 지원이 끝난 모델 이름으로 요청을 보내면 서버는 그 모델을 찾을 수 없다는 오류를 돌려줍니다. 내 코드는 그대로인데 상대편 서버의 모델 목록이 바뀐 것이라, 비개발자 입장에서는 "아무것도 안 했는데 고장 났다"처럼 느껴지는 거죠.

Anthropic 문서를 보면 모델 이름은 크게 두 종류입니다. 하나는 claude-sonnet-4-20250514처럼 날짜가 붙은 이름으로, 특정 시점의 모델 버전(스냅샷)을 가리킵니다. 다른 하나는 claude-sonnet-4-5처럼 날짜 없이 쓰는 별칭(alias)으로, 해당 계열의 최신 버전을 가리킵니다.

구분장점주의할 점
날짜가 붙은 모델명같은 버전을 계속 써서 답변 품질이 일정함지원 종료되면 그날부터 오류가 남
별칭(날짜 없는 이름)최신 버전으로 자동으로 따라감버전이 바뀌면 답변 형식이 조금 달라질 수 있음

어느 쪽이 정답이라기보다, 내 앱에 무엇이 더 중요한지에 따라 고르면 됩니다. 저처럼 혼자 운영하는 작은 앱이라면 별칭을 쓰되 가끔 결과를 직접 확인하는 방식이 관리가 편했습니다.

API 오류 코드, 이것만 알아도 절반은 해결

이번에는 404였지만, AI API를 쓰다 보면 다른 숫자의 오류도 만나게 됩니다. 오류 메시지 맨 앞의 숫자(HTTP 상태 코드)만 봐도 어디를 먼저 확인해야 할지 감이 옵니다. 아래는 일반적인 의미를 정리한 것입니다.

코드뜻먼저 확인할 것
400요청 형식이 잘못됨보내는 값의 이름과 형식, 최대 길이
401인증 실패API 키가 맞는지, 배포 환경에 키가 등록됐는지
403권한 없음계정이나 키에 해당 기능 권한이 있는지
404대상을 찾을 수 없음모델명 오타, 지원 종료된 모델, 요청 주소
429요청이 너무 많음사용량 한도, 잠시 후 다시 시도
500대서버 쪽 문제나 과부하내 코드보다는 서비스 상태, 잠시 후 재시도

숫자만으로 원인을 단정할 수는 없지만, 적어도 "내 코드를 뒤져야 하는지, 기다려야 하는지"는 빨리 가를 수 있습니다. 이번에 제가 GitHub 커밋 이력과 Vercel 로그부터 뒤졌던 것도, 404의 뜻을 먼저 알았다면 훨씬 짧게 끝났을 겁니다.

비개발자를 위한 재발 방지 체크리스트

같은 일이 또 생기지 않게 하려면 거창한 기술보다 몇 가지 습관이 중요합니다. AI 앱을 직접 운영하는 비개발자라면 아래 항목을 한 번 점검해 보세요.

  1. 모델명은 한 곳에서만 관리하기. 코드 여러 곳에 모델명을 흩어 두면 바꿀 때 빠뜨리기 쉽습니다. Vercel 같은 배포 서비스의 환경 변수에 모델명을 넣어 두면, 다음에는 코드를 고치지 않고 설정값만 바꾼 뒤 다시 배포하면 됩니다.
  2. 공식 문서 두 곳을 북마크하기. 모델 목록과 지원 종료 안내 페이지를 즐겨찾기에 넣어 두고 가끔 확인합니다.
  3. API 계정 이메일 확인하기. 서비스 변경 공지는 가입한 이메일로 오는 경우가 많으니, 스팸함까지 한 번씩 살펴보세요.
  4. 사용자에게 보이는 오류 문구 다듬기. "API 오류 404" 대신 "잠시 후 다시 시도해 주세요" 같은 안내를 보여 주고, 자세한 오류는 로그에 남기도록 AI에게 요청하면 됩니다.
  5. AI에게 에러를 물어볼 때 비밀 정보 지우기. 에러 메시지를 붙여 넣기 전에 API 키나 개인정보가 섞여 있지 않은지 확인하세요.

자주 묻는 질문

Q. 404 오류는 모두 모델명 문제인가요?
아닙니다. 요청 주소를 잘못 적었거나, 존재하지 않는 파일이나 페이지를 불렀을 때도 404가 납니다. 다만 AI API에서 "model"이라는 단어와 함께 404가 나왔다면 모델명부터 의심해 보는 것이 빠릅니다.

Q. 비개발자도 Vercel 환경 변수를 바꿀 수 있나요?
네. Vercel 프로젝트의 Settings 메뉴에 있는 Environment Variables에서 값을 바꿀 수 있습니다. 바꾼 값은 다시 배포해야 반영된다는 점만 기억하면 됩니다.

Q. 모델을 바꾸면 앱 결과도 달라지나요?
달라질 수 있습니다. 같은 요청이라도 모델 버전에 따라 답변 길이나 형식이 조금씩 다를 수 있으니, 모델명을 바꾼 뒤에는 핵심 기능을 직접 몇 번 눌러 보고 결과를 확인하는 것이 좋습니다.

마무리 정리

AI API를 쓰는 앱을 운영하다 보면 이런 일이 종종 생깁니다. 내가 건드린 게 없는데 갑자기 에러가 나면, 먼저 API 모델명이 바뀐 건 아닌지 확인해보세요. Anthropic뿐 아니라 OpenAI, Google도 모델명을 주기적으로 업데이트하니까요.

저처럼 비개발자가 AI 도움으로 앱을 만들어서 운영하고 있다면, 에러 메시지를 두려워하지 말고 읽어보는 습관이 제일 중요한 것 같습니다. 대부분의 에러는 메시지 안에 이미 답이 있어요.

지금 aitestu.com은 다시 정상 작동 중입니다. 교재 사진 찍으면 AI가 시험문제 만들어주는 앱인데, 관심 있으신 분은 한번 써보세요.

함께 읽으면 좋은 글

목록으로

이 블로그 검색

Copyright © The ISSUEFEED. All rights reserved.
새 글 소식을 RSS로 받아보세요 AI 활용법, 비개발자의 앱 개발기, 직장인 투자일기를 꾸준히 기록합니다.
RSS로 구독하기