Anthropic OAuth 토큰 사용 시 발생하는 의문의 429 에러 해결 방법

실용적 조언

Anthropic OAuth 토큰 사용 시 시스템 프롬프트에 'You are Claude Code, Anthropic's official CLI for Claude.'를 반드시 포함하세요.

섹션별 상세

작성자는 Claude Code와 동일한 OAuth 토큰을 사용하는 LLM 프록시를 구축하던 중 Claude 3.5 Sonnet 모델에서만 지속적인 429 레이트 리밋 에러가 발생하는 문제를 겪었다. Anthropic SDK와 필요한 모든 베타 헤더를 설정했음에도 불구하고, Haiku는 정상 작동하는 반면 Sonnet은 재시도 헤더도 없는 불분명한 에러를 반환했다.

문제 해결의 실마리는 오픈소스 프로젝트인 OpenClaw의 Anthropic 프로바이더 소스 코드에서 발견되었다. 해당 코드에는 OAuth 토큰 사용 시 반드시 Claude Code의 정체성을 시스템 프롬프트에 포함해야 한다는 주석과 로직이 포함되어 있었다.

Anthropic API는 헤더나 토큰 유형, User-Agent 문자열이 아닌 시스템 프롬프트의 내용을 기준으로 요청을 특정 레이트 리밋 풀에 할당한다. 'You are Claude Code, Anthropic's official CLI for Claude.'라는 문구가 포함되어야만 일반 API 풀보다 높은 별도의 Claude Code 전용 풀을 사용할 수 있게 된다.

javascript

// For OAuth tokens, we MUST include Claude Code identity
if (isOAuthToken) {
  params.system = [{
    type: "text",
    text: "You are Claude Code, Anthropic's official CLI for Claude.",
  }];
}

OAuth 토큰 사용 시 시스템 프롬프트에 Claude Code 식별 문구를 추가하여 레이트 리밋 문제를 해결하는 로직

이러한 메커니즘은 Anthropic의 공식 문서나 SDK 가이드 어디에도 명시되어 있지 않은 비공식적인 동작 방식이다. 시스템 프롬프트라는 콘텐츠 영역이 인프라 수준의 속도 제한 정책에 직접적인 영향을 미친다는 점이 기술적으로 이례적인 사례로 확인됐다.

용어 해설

오픈 인증(OAuth): — 사용자가 비밀번호를 공유하지 않고도 제3자 애플리케이션에 자신의 데이터에 대한 접근 권한을 부여할 수 있게 해주는 개방형 표준 프로토콜이다. Anthropic API에서는 Claude Code와 같은 도구가 사용자 권한으로 API를 호출할 때 사용된다. 보안을 유지하면서도 서비스 간 통합을 가능하게 하는 핵심 인증 메커니즘이다.
속도 제한(Rate Limiting): — 네트워크 서비스에서 특정 시간 동안 허용되는 요청의 수를 제한하는 기술적 조치이다. 시스템 과부하를 방지하고 공정한 자원 배분을 위해 사용되며, 제한을 초과할 경우 429 에러를 반환한다. API 제공업체는 사용자 등급이나 토큰 유형에 따라 서로 다른 제한 풀을 운영하기도 한다.
시스템 프롬프트(System Prompt): — LLM이 대화를 시작하기 전에 모델의 역할, 제약 조건, 행동 지침을 정의하는 최상위 지시문이다. 모델의 응답 스타일과 안전 가이드라인을 결정하는 데 결정적인 역할을 한다. 최근에는 이 프롬프트의 내용이 API의 인프라적 처리 방식이나 속도 제한 정책에 영향을 미치는 사례가 발견되고 있다.
429 요청 과다 에러(429 Too Many Requests): — 클라이언트가 서버의 속도 제한(Rate Limit)을 초과하여 너무 많은 요청을 보냈을 때 발생하는 HTTP 상태 코드이다. 일반적으로 서버는 언제 다시 요청할 수 있는지 알려주는 Retry-After 헤더를 함께 보내야 한다. 이 에러가 발생하면 요청 빈도를 줄이거나 할당된 레이트 리밋 풀을 확인해야 한다.

언급된 도구

Claude Code추천

Anthropic의 공식 CLI 도구

OpenClaw추천

AI 에이전트 실행 도구