[나의 앱개발기] 어느 날 갑자기 AI 앱이 먹통됐다 - API 모델명 변경 에러 해결 후기
분명히 어제까지는 잘 됐습니다. 아무것도 건드린 게 없어요. 코드도 그대로, 서버도 그대로인데 갑자기 앱이 먹통이 됐습니다.
제가 만든 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이 모델명을 바꿔버린 것.
Anthropic은 Claude 모델을 주기적으로 업데이트합니다. 문제는 업데이트하면서 기존 모델명을 그냥 없애버리는 경우가 있다는 거예요. 제가 코드에 박아놓은 모델명은 claude-sonnet-4-20250514 였는데, 어느 순간 이 모델이 지원 종료된 겁니다.
Anthropic 공식 문서를 확인해보니 현재 사용 가능한 모델명은 달라져 있었습니다.
| 기존 모델명 (사용 불가) | 변경된 모델명 (현재 사용 가능) |
|---|---|
| claude-sonnet-4-20250514 | claude-sonnet-4-5 |
| claude-haiku-4-5-20251001 | claude-haiku-4-5 |
날짜가 붙어있던 버전 표기가 사라지고 심플하게 바뀐 거였습니다. 원인을 찾고 나니 허탈할 정도로 단순한 문제였어요.
* 해결 방법은 딱 한 줄.
저는 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 공식 문서에서 확인하는 게 좋습니다.
여기 들어가면 현재 사용 가능한 모델명 전체 목록이 나옵니다. API 에러가 나면 제일 먼저 여기서 모델명을 확인해보세요.
* 비개발자가 이런 에러를 만났을 때.
저는 개발자가 아닙니다. Claude AI랑 같이 앱을 만든 직장인이에요. 그래서 이런 에러가 처음 떴을 때 진짜 당황했습니다. 코드를 다 갈아엎어야 하나 싶었거든요.
근데 에러 메시지를 차분히 읽어보는 것, 이게 핵심이더라고요. 에러 메시지는 항상 원인을 담고 있습니다. 영어라서 읽기 싫어도 그냥 Claude한테 에러 메시지 통째로 붙여넣고 "이게 무슨 에러야?" 라고 물어보면 바로 답이 나왔습니다.
이번 에러 해결 과정을 정리하면 이렇습니다.
에러 메시지 복사
Claude한테 붙여넣기
원인 파악 → 모델명 한 줄 수정 → 해결!
총 걸린 시간이 15분이었습니다. 개발자였으면 1분이었겠지만, 비개발자도 충분히 혼자 해결할 수 있는 수준이에요.
* 마무리 정리.
AI API를 쓰는 앱을 운영하다 보면 이런 일이 종종 생깁니다. 내가 건드린 게 없는데 갑자기 에러가 나면, 먼저 API 모델명이 바뀐 건 아닌지 확인해보세요. Anthropic뿐 아니라 OpenAI, Google도 모델명을 주기적으로 업데이트하니까요.
저처럼 비개발자가 AI 도움으로 앱을 만들어서 운영하고 있다면, 에러 메시지를 두려워하지 말고 읽어보는 습관이 제일 중요한 것 같습니다. 대부분의 에러는 메시지 안에 이미 답이 있어요.
지금 aitestu.com은 다시 정상 작동 중입니다. 교재 사진 찍으면 AI가 시험문제 만들어주는 앱인데, 관심 있으신 분은 한번 써보세요.