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

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

핵심 요약

Anthropic OAuth 토큰 사용 시 시스템 프롬프트에 특정 식별 문구를 포함해야 Claude Code 전용 레이트 리밋 풀을 배정받아 429 에러를 피할 수 있다.

배경

Anthropic OAuth 토큰을 이용해 프록시를 구현하던 중 특정 모델에서만 발생하는 레이트 리밋 에러의 원인이 시스템 프롬프트 내용에 있음을 발견하고 이를 공유했다.

의미 / 영향

이 토론을 통해 Anthropic API의 레이트 리밋 정책이 시스템 프롬프트 내용과 결합되어 있음이 확인됐다. 개발자들은 OAuth 기반 통합 시 문서화되지 않은 이러한 식별 로직을 반드시 고려해야 안정적인 서비스 운영이 가능하다.

커뮤니티 반응

작성자의 발견에 대해 놀라움을 표하며, API 설계가 프롬프트 내용에 의존한다는 점이 이례적이라는 반응이 주를 이룬다.

주요 논점

01찬성다수

시스템 프롬프트 식별 문구 추가가 OAuth 토큰 사용 시 레이트 리밋 문제를 해결하는 유일한 방법이다.

합의점 vs 논쟁점

합의점

OAuth 토큰 사용 시 Sonnet 모델에서 429 에러가 발생하는 현상이 실재한다.
시스템 프롬프트에 특정 문구를 넣으면 에러가 즉시 해결된다.

논쟁점

API 인프라 정책이 헤더가 아닌 프롬프트 텍스트에 의존하는 설계의 적절성 여부

실용적 조언

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 가이드 어디에도 명시되어 있지 않은 비공식적인 동작 방식이다. 시스템 프롬프트라는 콘텐츠 영역이 인프라 수준의 속도 제한 정책에 직접적인 영향을 미친다는 점이 기술적으로 이례적인 사례로 확인됐다.

실무 Takeaway

Anthropic OAuth 토큰을 사용하여 Claude 모델을 호출할 때 시스템 프롬프트에 특정 식별 문구가 없으면 낮은 레이트 리밋이 적용되어 429 에러가 빈번하게 발생할 수 있다.
레이트 리밋 풀 할당이 HTTP 헤더가 아닌 시스템 프롬프트 텍스트 내용에 의존하는 특이한 API 설계 구조를 가지고 있다.
'You are Claude Code, Anthropic's official CLI for Claude.' 문구를 시스템 프롬프트에 추가하는 것만으로도 Sonnet 모델의 레이트 리밋 문제를 즉시 해결할 수 있다.

언급된 도구

Claude Code추천

Anthropic의 공식 CLI 도구

OpenClaw추천

AI 에이전트 실행 도구