SelfCheck_AI Troubleshooting_2 (26.01.25)

🛠️ 2. Troubleshooting (트러블슈팅)

이번 스프린트(1.22 ~ 1.25)에서 OpenAI API를 연동하며 겪었던 주요 에러 3가지와 그 해결 과정을 상세히 기록합니다.

Issue 1. IllegalArgumentException: The template string is not valid

🚨 문제 상황
Spring AI의 ChatClient를 사용하여 AI에게 요청을 보냈으나, 서버 로그에 IllegalArgumentException이 발생하며 요청이 실패했습니다.

java.lang.IllegalArgumentException: The template string is not valid.
    at org.springframework.ai.chat.prompt.PromptTemplate.<init>(PromptTemplate.java:85)
    ...

🔍 원인 분석
Spring AI의 기본 PromptTemplate 클래스는 문자열 내부의 중괄호 { }를 변수 치환자(Placeholder)로 인식.
하지만 제가 작성한 시스템 프롬프트에는 AI에게 JSON 응답 형식을 예시로 보여주기 위해 중괄호가 포함된 JSON 문자열이 들어 있었습니다.

// 문제가 된 프롬프트 예시
String systemPrompt = """
    ...
    반드시 아래 형식으로 응답하세요:
    {  <-- Spring AI는 이걸 변수의 시작으로 착각함
        "score": ...
    }
""";

PromptTemplate은 이 중괄호를 보고 "여기에 어떤 값을 채워넣어야 하는데, 매칭되는 변수가 없다"고 판단하여 에러를 발생시킨 것.

✅ 해결 방법
PromptTemplate을 거치지 않고, SystemMessage와 UserMessage 객체를 직접 생성하여 메시지 리스트로 전달하는 방식을 사용했습니다. 이렇게 하면 템플릿 파싱 과정을 건너뛰고 문자열 그대로 AI에게 전송됩니다.

• 수정 전(에러 발생 코드)

// 템플릿 파싱을 시도하다가 JSON 중괄호 때문에 실패함
chatClient.prompt()
    .system(systemPrompt) 
    .user(userMessage)
    .call();

• 수정 후(해결된 코드 - Aiclient.java)

// Message 객체로 직접 감싸서 전달 (템플릿 파싱 우회)
chatClient.prompt()
    .messages(new SystemMessage(systemPrompt), new UserMessage(userMessage))
    .call();

Issue 2. 429 insufficient_quota (OpenAI Quota Exceeded)

🚨 문제 상황
코드를 완벽하게 수정했음에도 불구하고, AI 요청 시 429 상태 코드와 함께 아래와 같은 에러 메시지가 반환되었습니다.

{
    "error": {
        "code": "insufficient_quota",
        "message": "You exceeded your current quota, please check your plan and billing details."
    }
}

🔍 원인 분석
이 에러는 "API 사용 한도 초과" 또는 "잔액 부족"을 의미합니다.

• 오해: 저는 ChatGPT Plus(월 $20)를 구독 중이었기에 API도 무료로 사용할 수 있을 것이라 생각했습니다.
• ChatGPT(웹 채팅)와 OpenAI API(개발용)는 과금 체계가 완전히 분리되어 있습니다. API를 사용하려면 별도의 Credit(선불 충전금)이 필요합니다. 계정 생성 시 제공되는 무료 크레딧이 만료되었거나 소진되어 잔액이 $0 이었기 때문에 발생한 문제였습니다.

✅ 해결 방법
OpenAI Platform의 Billing Settings 페이지에서 Credit을 충전했습니다.

1. 카드 등록: 결제 수단을 등록합니다.
2. 크레딧 충전: 최소 금액인 $5 (약 7,500원)를 충전했습니다.
3. 설정 팁: Automatic recharge 옵션을 OFF로 설정하여, 의도치 않은 자동 결제를 방지하고 딱 충전한 금액만큼만 안전하게 테스트할 수 있도록 했습니다.

Issue 3. JSON 파싱 실패와 예외 처리 (AI_INVALID_RESPONSE)

🚨 문제 상황
AI가 응답을 주긴 하는데, 간혹 ObjectMapper가 이를 DTO로 변환하지 못하고 에러를 뱉는 경우가 발생

🔍 원인 분석
LLM(거대언어모델)은 기본적으로 텍스트 생성기이기 때문에, JSON 형식으로 달라고 요청해도 친절하게(?) 마크다운 코드 블록을 씌워서 주는 경우가 많습니다.

// AI가 실제로 준 응답 (Raw String)
{
   "score": { ... },
   "feedback": [ ... ]
}
```  <-- 뒤에 백틱(```)이 붙어있음

Java의 ObjectMapper는 순수한 JSON 문자열만 파싱할 수 있기 때문에, 앞뒤에 붙은 \```json 태그 때문에 파싱 에러가 발생한 것.

✅ 해결 방법
AI의 응답(Raw String)을 파싱하기 전에 전처리(Pre-processing) 과정을 추가하고, 파싱 실패 시 클라이언트에게 명확한 에러를 전달하도록 예외 처리를 강화했습니다.

1. 문자열 전처리 (replace)

// AiClient.java
String cleanJson = aiResponseRaw
        .replace("```json", "")  // 마크다운 시작 태그 제거
        .replace("```", "")      // 마크다운 끝 태그 제거
        .trim();                 // 공백 제거
        

2. 커스텀 예외 던지기
파싱 중 에러가 발생하면 시스템 내부 에러(500)를 그대로 보여주는 대신, 정의해둔 비즈니스 예외를 던집니다.

try {
    return objectMapper.readValue(cleanJson, ResumeResponse.class);
} catch (Exception e) {
    log.error("AI 처리 중 오류 발생: ", e);
    // "AI 응답을 처리할 수 없습니다"라는 의미의 커스텀 예외
    throw new BusinessException(ErrorCode.AI_INVALID_RESPONSE);
}

3. 전역 예외 처리(GlobalExceptionHandler)
BusinessException을 잡아서 프론트엔드가 이해하기 쉬운 표준 포맷으로 변환하여 반환합니다.

// GlobalExceptionHandler.java
@ExceptionHandler(BusinessException.class)
public ApiResponse<?> handleBusinessException(BusinessException e) {
    return ApiResponse.error(e.getErrorCode().name(), e.getMessage());
}