응답이 어긋났을 때: 진단·복구·원인 격리

4.1 오류 유형의 분류와 복구 전략 선택

Claude 애플리케이션의 오류는 세 갈래로 나뉩니다. 첫째, 잘못된 요청에서 오는 클라이언트 오류(4xx) — 인증 실패(401), 형식 오류(400), 요청 초과(413)는 코드나 파라미터를 고쳐야 사라집니다. 둘째, 서버 측 일시 오류 — 한도 초과(429 rate_limit_error), 과부하(529 overloaded_error), 5xx는 잠시 뒤 다시 시도하면 대개 풀립니다. 셋째, HTTP 오류는 아니지만 정상으로 오인하기 쉬운 응답 — 토큰 한도로 잘린 결과(stop_reason이 max_tokens)나 거절이 그렇습니다. 재시도 대상은 429·529·5xx로 한정하고, 지수 백오프(exponential backoff, 재시도 간격을 점점 늘리는 방식)에 지터(jitter, 무작위 편차로 동시 재시도 폭주를 막는 장치)를 더합니다. 클라이언트 오류는 재시도가 아니라 요청을 바로잡아야 합니다.

4.2 트레이스 분석으로 실패 유형 파악하기

트레이스(trace, 한 요청이 처리되는 전 과정의 기록)는 디버깅의 출발점입니다. 요청 파라미터, 시스템 프롬프트, 주고받은 메시지, 툴 호출, 모델 응답, stop_reason, 토큰 사용량, 지연 시간, 오류를 요청 식별자(request-id)와 함께 남겨 두면, 재현되지 않는 실패도 사후에 되짚을 수 있습니다. 이렇게 모인 기록에서 실패 유형이 드러납니다 — 근거 없는 사실을 지어내는 환각(hallucination), 엉뚱한 툴 선택, 토큰 한도로 인한 절단, 특정 입력에서만 튀는 지연, 형식이 어긋난 출력 등입니다. 응답 헤더로 돌려받는 request-id는 Anthropic 지원에 문의할 때 서버 기록과 맞대어 원인을 좁히는 열쇠가 됩니다.

4.3 문제의 출처 격리: 통합 계층인가, 모델 출력인가

무언가 잘못됐을 때 가장 먼저 가려야 할 것은, 문제가 우리 코드(통합 계층, integration layer — 요청 구성·인증·파싱·직렬화·툴 실행·재시도를 맡는 계층)에서 났는지 아니면 모델이 내놓은 출력 자체에서 났는지입니다. 판별법은 단순합니다. API가 돌려준 원본 응답을 그대로 열어 봅니다. 원본은 올바른데 사용자에게 닿는 결과가 어긋났다면 파싱·직렬화 같은 통합 계층 버그이고, 원본 응답 자체가 틀렸다면 프롬프트나 모델 쪽 문제입니다. 통합 계층 버그는 같은 입력에 늘 같은 결과로 재현되지만, 모델 출력 문제는 샘플링 탓에 매번 흔들립니다. 그래서 디버깅 중에는 temperature를 0으로 두어 결정성(determinism, 같은 입력에 같은 결과)을 확보한 뒤 원본을 대조합니다.

! 흔한 함정

• 모든 오류를 재시도로 덮으려는 습관 — 400·401 같은 클라이언트 오류는 재시도해도 같은 실패만 반복됩니다. 재시도 대상은 429·529·5xx로 한정해야 합니다.
• stop_reason을 확인하지 않고 응답 본문만 파싱 — max_tokens로 잘린 응답을 정상으로 착각하면 원인 불명의 데이터 누락으로 이어집니다.
• 원본 요청·응답을 확인하지 않은 채 성급히 모델 탓으로 결론 — 실제로는 파싱·직렬화 버그인 통합 계층 문제를 놓치게 됩니다.
• temperature를 고정하지 않고 디버깅 — 샘플링이 매번 달라지면 재현이 어렵습니다. 디버깅 중에는 temperature 0으로 결정성을 확보합니다.