Gemini API 405, 505 오류 해결과정 기록

잘 되던 페이지가 여기서 멈추면서 시작되었다

 

사이드 프로젝트 MBTI x Tarot | 성향 기반 타로 조언를 정리하던 중, Gemini API 호출에서 발생한 오류를 발견해 해결한 과정을 기록했습니다.

---

📌 문제 상황 (Problem)

Vercel 배포 환경에서 타로 리딩 결과 생성을 위해 Gemini API(/api/gemini)를 POST 요청으로 호출했을 때, 그동안 정상적으로 작동하던 부분에서 405 Method Not Allowed 오류가 발생했습니다.

// 에러문구
POST https://your-tarot-mbti.vercel.app/api/gemini 405 (Method Not Allowed)
Gemini 호출 실패: Error: 서버 오류: 405

---

🔍 트러블슈팅 및 해결 과정 (Troubleshooting & Solution)

❌ 1차 시도: API Route 메서드 검증 추가

HTTP 405("Method Not Allowed")가 메서드 문제로 추정되어, Stack Overflow와 AI의 조언에 따라 메서드 검증 로직을 추가했습니다.

Before

// src/pages/api/gemini.ts
export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const { question, card, mbti } = req.body;

  // ... 프롬프트 생성 로직 ...

  const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY!);
  const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });
  const result = await model.generateContent(prompt);
  const text = await result.response.text();

  res.status(200).json({ output: text });
}

After

// src/pages/api/gemini.ts
export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  // ✅ POST 메서드만 허용
  if (req.method !== "POST") {
    return res.status(405).json({ error: "Method Not Allowed" });
  }

  const { question, card, mbti } = req.body;

  // ✅ 필수 파라미터 검증
  if (!question || !card || !mbti) {
    return res.status(400).json({ error: "필수 파라미터가 누락되었습니다." });
  }

  try {
    // ... 프롬프트 생성 로직 ...

    const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY!);
    const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });
    const result = await model.generateContent(prompt);
    const text = await result.response.text();

    res.status(200).json({ output: text });
  } catch (error) {
    console.error("Gemini API 오류:", error);
    res.status(500).json({ error: "AI 응답 생성 중 오류가 발생했습니다." });
  }
}

이렇게 하니 이번엔 500 에러가 발생했습니다.

//에러문구
POST https://your-tarot-mbti.vercel.app/api/gemini 500 (Internal Server Error)
Gemini 호출 실패: Error: 서버 오류: 500

 

메서드 검증은 통과했지만 Gemini API 호출에 문제가 있다는 것을 알게 되었습니다.

---

❌ 2차 시도: 환경변수 및 API 키 확인

이전에 Gemini API 키 관련 메일(지금은 지웠나 찾을 수 없었음)을 받은 기억이 있어서, 혹시 키 문제일까 싶어 확인했습니다.

• Vercel 환경변수: ✅ 정상
• Google AI Studio에서 API 키 상태: ✅ 활성화
• 로컬 .env 파일: ✅ 정상

모두 정상 이었습니다.
즉, API Key 문제는 아니었습니다.

---

💡 진짜 원인 발견!

2차 시도까지 실패하고 구글링으로 Gemini API 공식 트러블슈팅 문서에서는 500 에러 정보를

HTTP 코드	상태	설명	예	해결 방법
500	내부	Google 측에서 예기치 않은 오류가 발생했습니다.	입력 컨텍스트가 너무 깁니다.	입력 컨텍스트를 줄이거나 일시적으로 다른 모델 (예: Gemini 1.5 Pro에서 Gemini 1.5 Flash로)로 전환하여 작동하는지 확인합니다. 또는 잠시 기다렸다가 요청을 다시 시도하세요. 다시 시도한 후에도 문제가 계속되면 Google AI Studio의 의견 보내기 버튼을 사용하여 문제를 신고해 주세요.

Google AI Studio 출시노트에서 결정적인 내용을 발견했습니다.

2025년 9월 29일
다음 Gemini 1.5 모델은 이제 지원 중단되었습니다.

• gemini-1.5-pro
• gemini-1.5-flash-8b
• gemini-1.5-flash ← 적용중인 모델

제가 사용하던 모델이 2025년 9월 29일부로 완전히 지원 중단되었고, 10월 10일 시점에는 작동하지 않는 모델로 요청을 보내고 있었던 것입니다.

공식 문서에는 "지원 중단된 모델 → 500 에러"라는 명시는 없었지만, 시간상으로나 상황상 이것이 원인이 확실했습니다.

---

✅ 해결 방법

단 한 줄, 현재 지원중인 모델명으로 수정하고

// ❌ Before (500 오류 발생)
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });

// ✅ After (정상 작동)
const model = genAI.getGenerativeModel({ model: "gemini-2.0-flash" });

배포 후 테스트 결과, 정상적으로 응답이 생성되었고 오류는 완전히 해결되었습니다.

---

🚀 배운 점 (Lessons Learned)

1. 에러 코드는 ‘단서’일 뿐, ‘원인’은 아니다

HTTP 405나 500 코드는 “문제의 단서”일 뿐, 원인을 직접적으로 설명하지는 않으며, 실제 원인은 API 정책이나 외부 요인일 수 있다는 걸 배웠습니다.

이번 경험을 통해 사용하는 api에 문제가 발생하면 공식문서를 꼭 확인해야 함을 다시 한 번 깨달았습니다.  

2. 500 에러도 명확한 메시지를 주지 않는다

Gemini API는 deprecated 모델을 호출해도 명확한 메시지 없이 500만 반환합니다.

토큰 문제뿐 아니라 모델 버전도 의심 대상에 포함시켜야 함을 알게 되었습니다.

3. 외부 API는 언제든 변할 수 있다

내 코드는 그대로였지만, API의 버전 정책 변화 하나로 서비스 전체가 멈출 수 있다는 걸 배웠습니다.

앞으로는 정기적으로 공식 출시노트를 확인하고, 사용하는 버전에 대한 지원여부도 상시 확인해야함을 알게 되었습니다.

4. 디버깅의 체계적 접근

이번 트러블슈팅에서 거친 단계:

1. ✅ 코드 레벨: 메서드 검증, 파라미터 검증
2. ✅ 인프라 레벨: 환경변수
3. ✅ 외부 의존성: 버전 확인 ← 여기서 해결!

문제가 내 코드에 있다고 가정하고 시작하되, 외부 요인도 반드시 의심해야 한다는 교훈을 얻었습니다.

---

🔗 참고 자료

• Gemini API 공식 문서
• Gemini API 출시노트
• Gemini API 문제해결가이드

---

AI에게 관련한 향후 개선방법 물어보니 모델 버전 환경변수화, Fallback 메커니즘 (자동 전환) 등을 제안해줬는데 차후 실제로 적용해보고, 효과가 있다면 별도 포스트로 다룰 예정입니다.