Claude API 오류 — 속도 제한, 400, 500, 529 해결

Claude API 오류는 거의 항상 몇 가지 중 하나입니다: 잘못된 요청, 속도 제한 초과, 서버 측 장애, 과부하. 각 코드와 해결법을 살펴봅니다.

400 — 잘못된 요청

400은 요청 자체의 문제입니다: 너무 긴 컨텍스트, 잘못된 메시지 형식, 존재하지 않는 모델 이름. 전체 입력 토큰이 모델 윈도우에 들어가는지, 모델 이름이 올바른지 확인하세요.

에이전트 작업에서 흔한 원인은 tool_use/tool_result 블록의 불일치입니다. 각 tool_use에 대응하는 tool_result가 있는지 확인하세요.

429 — 속도 제한 초과

429는 분당 요청 또는 토큰 한도를 초과했다는 뜻입니다. 응답에 보통 retry-after 헤더가 있으니 그만큼 기다린 뒤 재시도하세요.

지수 백오프를 구현하세요: 429마다 대기 시간을 두 배로. 여러 업스트림 계정 풀을 가진 게이트웨이는 부하를 분산해 429 빈도를 낮춥니다.

500과 529 — 장애와 과부하

500은 일시적인 서버 내부 오류이니 지연 후 재시도하세요. 529(overloaded_error)는 업스트림 과부하를 의미하며 더 긴 지수 백오프가 필요합니다.

여러 업스트림 계정을 가진 게이트웨이는 500/529 시 정상 계정으로 자동 전환하므로 직접 호출보다 이런 오류를 훨씬 적게 보게 됩니다.

재시도 로직

견고한 클라이언트는 429/500/529에 지수 백오프로 재시도하고, 400은 재시도하지 않습니다(요청 오류라 재시도가 무의미).

특정 모델에서 오류가 반복되면 서버를 탓하기 전에 모델 이름과 한도부터 확인하세요.

# 재시도 로직 예시
for attempt in range(5):
    r = call_claude(...)
    if r.status in (429, 500, 529):
        time.sleep(2 ** attempt)   # 지수 백오프
        continue
    break  # 400은 재시도 안 함

FAQ

Claude API 429 오류는 무슨 뜻인가요?
분당 요청/토큰 한도 초과입니다. retry-after 시간만큼 기다린 뒤 지수 백오프로 재시도하세요.

400 오류는 어떻게 고치나요?
요청을 점검하세요: 컨텍스트 길이, 메시지 형식, 모델 이름, tool_use/tool_result 짝. 400은 재시도해도 소용없습니다.

529 overloaded_error는 어떻게 하나요?
업스트림 과부하이니 긴 지수 백오프로 재시도하세요. 계정 풀 게이트웨이는 이 오류 빈도를 낮춥니다.

게이트웨이가 오류를 줄여주나요?
네 — 여러 업스트림 계정 풀로 500/529 시 전환하므로 오류를 덜 보게 됩니다.