Teapot Router / 문서
Claude Code 문제 해결: 연결, 401, 쿼터
에러 유형별로 접근: 네트워크와 프록시, 키와 주소, 잔액과 쿼터 — 세 부류의 실패에 세 가지 점검법.
작업 공간 열기연결/타임아웃: 먼저 네트워크 경로
- CLI는 시스템 프록시를 물려받지 않습니다. `echo $https_proxy`를 실행해 비어 있으면 export 후 재시도.
- VSCode 확장은 자체 네트워크 스택을 써서 시스템 프록시나 환경변수를 물려받지 않을 수 있습니다 — 확장 설정에서 프록시를 지정하세요.
- 커스텀 엔드포인트라면 ANTHROPIC_BASE_URL의 불필요한 문자나 슬래시를 확인하고, 공식 URL과 게이트웨이 URL을 섞지 마세요.
다른 네트워크(핫스팟)에서 되고 내 네트워크에서 안 되면 순수 네트워크 문제이며 키와 무관합니다.
401/403: 키와 주소 확인
- 401은 대개 키 문제: 복사 누락(앞뒤 공백), 취소/만료, 다른 사업자의 키.
- 커스텀 엔드포인트에서는 키와 주소가 한 쌍 — A 사 키에 B 사 URL은 항상 401입니다.
- settings.js의 env 필드명을 잘못 쓰면 조용히 기본 엔드포인트로 폴백할 수 있습니다: 설정한 것 같아도 공식 URL로 가고 있는 상태.
취소된 키는 복구되지 않습니다. 키 교체 후 클라이언트를 재시작하세요.
429·쿼터·모델 없음
- 429는 속도 제한: 윈도우 리셋을 기다리거나 동시성을 낮추세요.
- '쿼터 부족'은 두 층위: 계정 잔액과 해당 키의 독립 한도 — 키 한도는 사용 상한이지 추가 충전이 아닙니다.
- '모델을 찾을 수 없음': 클라이언트의 모델 ID가 '모델' 카탈로그와 정확히 일치(대소문자·버전)하는지 확인.
각 요청의 모델/토큰/비용은 '사용 기록'에서 확인 가능 — 해결 후 조용한 재시도로 이중 청구가 없었는지 한 건 대조하세요.