강의 계획 레슨 250개 중 121번째 · 진짜 LLM 호출하기
진짜 LLM 호출하기

API 오류 처리하기

실제 네트워크 호출은 실패하고, 실무 LLM 클라이언트의 성패는 어떻게 반응하느냐에 달려 있어요. 가장 쓸모 있는 본능은 실패를 두 통으로 나누는 거예요: 다시 시도할 가치가 있는 것(아마 풀릴 일시적인 문제)과 요청에서 고쳐야 하는 것(아무리 다시 시도해도 소용없는 내 호출의 버그). HTTP 상태 코드가 어느 통인지 알려 줘요.

실제 코드에서는 각각 .status_code를 가진 SDK의 타입 있는 예외를 잡아요(보여 주기만 해요 -> 네트워크는 부르지 않아요):

import anthropic
try:
    resp = client.messages.create(model="claude-opus-5-5", max_tokens=1024,
                                  messages=history)
except anthropic.RateLimitError:          # HTTP 429 -> back off and retry
    ...
except anthropic.APIStatusError as e:     # any other 4xx/5xx, has e.status_code
    if should_retry(e.status_code):
        ...   # retry with backoff
    else:
        raise # 400/401/403/404 -> a bug in YOUR request, surface it

상태 코드별 통:

  • 다시 시도 -> 408(요청 시간 초과), 409(충돌), 429(속도 제한), 그리고 502, 503(사용 불가), 529(과부하) 같은 500에서 599까지의 모든 서버 오류. 일시적이에요: 기다렸다가 다시 시도하세요. 응답에 retry-after 헤더가 있으면 적어도 그만큼 기다리세요.
  • 요청 고치기 -> 400(잘못된 요청), 401(잘못된 API 키), 403(금지됨), 404(틀린 모델이나 경로). 잘못된 호출을 다시 시도하면 할당량만 태워요.
  • 알 수 없음 -> 그 밖의 모든 것(200 같은 성공 포함): 다시 시도해도 안전하다고 가정하지 마세요.

작은 함수 두 개를 만들어요. classify_error(status)는 통 이름을 돌려줘요: "retry", "fix-request", "unknown". should_retry(status)는 불리언을 돌려줘요 -> 상태가 다시 시도 집합에 있을 때 정확히 True, 아니면 False.

이 레슨은 다시 시도할지 말지를 정해요. 시도 사이의 기다림은 따로인 기술이에요. production-patterns 모듈이 지수 백오프(시도마다 지연을 두 배로: 1초, 2초, 4초 ...)를 다루고, 그 위에 지터를 더해요 -> 약간의 무작위 추가 대기 -> 같은 순간에 튕겨 나간 클라이언트 무리가 모두 같은 박자에 다시 시도해서 서버를 또 짓밟지 않도록요("우르르 몰려드는 무리"). 상태 표가 여러 다른 답(429 -> retry, 400 -> fix-request, 200 -> unknown)을 내도록 만드세요. 그래서 상수 하나로는 통과할 수 없어요.

내 차례

408(요청 시간 초과), 409(충돌), 429(속도 제한)와 500에서 599까지의 모든 서버 오류(529는 과부하)에는 "retry"를, {400, 401, 403, 404}에는 "fix-request"를, 그 밖의 것에는 "unknown"을 돌려주는 classify_error(status)를 쓰세요. classify_error(status)가 "retry"일 때 정확히 불리언 True를, 아니면 False를 돌려주는 should_retry(status)를 쓰세요. (공식 Anthropic SDK가 쓰는 것과 같은 규칙이에요: 이 상태들과 연결 오류를 기본으로 두 번 다시 시도하고, retry-after 헤더가 요구하는 만큼 기다려요. 실제 코드에서는 대개 이걸 직접 쓰기보다 max_retries를 설정하지만, 한 번 써 보면 그게 무엇을 하는지 알게 돼요.)

이 레슨에서 문제를 발견했나요? 알려 주세요 · 이 레슨에 대해 묻기

이 연습은 곧 열려요

앞의 레슨을 마치면 이 레슨이 열려요. 강좌 전체가 무료이고 계정도 필요 없으며, 이 레슨은 지금 바로 읽을 수 있어요.