Anthropic API 에러 분류와 재시도 전략

자주 만나는 에러

| 코드 | 의미 | 재시도? | |-----|------|--------| | 400 | invalid_request | ❌ 로직 버그 | | 401 | authentication_error | ❌ API 키 확인 | | 403 | permission_error | ❌ 조직 권한 | | 429 | rate_limit_error | ✅ 지수 백오프 | | 500 | api_error | ✅ 1~2회 | | 529 | overloaded_error | ✅ 백오프 + jitter | | timeout | 네트워크 | ✅ 2회 |

표준 재시도 래퍼

import Anthropic from "@anthropic-ai/sdk"

async function withRetry<T>(fn: () => Promise<T>, max = 5): Promise<T> {
  let lastErr: unknown
  for (let i = 0; i < max; i++) {
    try {
      return await fn()
    } catch (err) {
      lastErr = err
      const status = (err as any)?.status
      const retryable = [429, 500, 529].includes(status) ||
                        (err as any)?.type === "overloaded_error"
      if (!retryable) throw err
      const base = Math.min(1000 * 2 ** i, 30_000)
      const jitter = Math.random() * 500
      await new Promise(r => setTimeout(r, base + jitter))
    }
  }
  throw lastErr
}

// 사용
const msg = await withRetry(() =>
  client.messages.create({ model: "claude-sonnet-4-6", /* ... */ })
)

SDK 내장 재시도

Anthropic TypeScript SDK는 기본 2회 재시도가 켜져 있다. 끄거나 늘리려면:

const client = new Anthropic({ maxRetries: 5 })

절대 재시도하면 안 되는 상황

1. 결제 실패 툴 호출 — 중복 청구 위험
2. 이메일 전송 툴 — 스팸으로 분류됨
3. 사용자 측 400 에러 — 프롬프트가 잘못된 것. 재시도해도 같은 결과

529 overloaded 대응

Anthropic이 전체적으로 트래픽 몰릴 때 나온다. 이땐:

• 지수 백오프 필수 (1s → 2s → 4s → 8s...)
• jitter 추가: 전 세계 클라이언트가 동시 재시도하면 2차 폭주
• Haiku로 폴백: Sonnet 529면 Haiku 4.5로 자동 전환하는 것도 전략

체크리스트

• [ ] 재시도 대상 에러 화이트리스트
• [ ] jitter 들어있나
• [ ] 최대 대기시간 상한 (30s)
• [ ] 비멱등 툴은 재시도 제외