문제 해결

요청은 세 단계를 거치며, 각 단계마다 고유한 오류가 있습니다.

AI CLI  →  sotatek-proxy (127.0.0.1:3817)  →  Bifrost gateway  →  Provider (Anthropic/OpenAI/…)

출처	식별 방법
sotatek-proxy	본문 {"error":"upstream unreachable","proxy":"sotatek-proxy"} (HTTP 502), 또는 X-Git-Remote-Warning 응답 헤더
Gateway	본문 {"error":{"message":...}}. 거버넌스 오류에는 "type"도 있습니다(예: virtual_key_blocked). 2.1–2.4의 403은 message만 있습니다
Provider	Provider 고유의 message/type, 대개 Provider의 HTTP 상태 그대로

Admin/IT에 오류를 보고할 때

발생 시각과 키의 마지막 8자를 보내 주세요. 키 전체는 절대 보내지 마세요.

1. sotatek-proxy 오류

Connection refused

프록시가 실행 중이 아닙니다. sotatek-proxy status로 확인하고 sotatek-proxy start로 시작하세요. CLI가 ANTHROPIC_BASE_URL=http://127.0.0.1:3817/anthropic를 가리키는지도 확인하세요.

HTTP 502 upstream unreachable

프록시가 gateway에 연결하지 못했습니다(네트워크, VPN, DNS 또는 gateway 다운). 네트워크/VPN을 확인하고 sotatek-proxy logs를 보세요. 네트워크가 정상인데도 계속되면 Admin/IT에 문의하세요.

X-Git-Remote-Warning / X-Git-Remote-Remedy 헤더

프록시가 git remote를 확인하지 못해도 요청은 그대로 전달하며, 원인을 이 두 응답 헤더로 알려 줍니다. 이후 gateway가 2.1 또는 2.2의 403으로 거부할 수 있습니다. 오류가 나는 저장소에서 sotatek-proxy doctor를 실행해 원인과 해결 방법을 확인하세요.

원인 코드	의미	해결
not_a_repo	CLI를 git 저장소 밖에서 시작함(프록시는 상위 3단계까지 탐색)	저장소 안에서 CLI를 다시 시작
no_remote	저장소에 remote가 없음	git remote add origin <url>
git_not_found	서비스가 git을 찾지 못함	macOS: xcode-select --install (launchd는 최소 PATH만 보므로 Homebrew git은 /usr/local/bin에 심볼릭 링크 필요). Windows: Git for Windows 설치 후 서비스 재시작. Linux: git 설치 후 서비스 재시작
git_shim_broken	macOS /usr/bin/git이 xcrun 스텁이며 OS 업그레이드 후 깨짐	xcode-select --install
git_ownership	다른 사용자 소유 저장소를 git이 거부	git config --global --add safe.directory <저장소 경로>
git_permission	프록시가 저장소를 읽을 수 없음	저장소 소유자/권한과 서비스 실행 사용자 확인
git_timeout	git remote -v가 2초 초과(네트워크 드라이브, credential helper 정지)	해당 저장소에서 git remote -v 시간 측정
git_exec_failed	기타 이유로 git 실패	git remote -v를 직접 실행해 git의 오류 확인
pid_not_found, cwd_not_found	검사 전에 클라이언트 프로세스가 종료됨	가끔이면 무시, 계속되면 sotatek-proxy doctor 실행
inspect_timeout, inspect_failed	프로세스 검사 도구(lsof, /proc, Windows TCP 테이블) 실패 또는 시간 초과	sotatek-proxy doctor 실행 후 OS별 안내에 따름
non_loopback_peer	클라이언트가 loopback으로 연결하지 않음	http://127.0.0.1:3817 사용

2. Gateway 오류

Gateway는 다음 순서로 확인합니다: 키 인증 → git 컨텍스트 → git/프로젝트 가드 → 프로젝트 모델 가드 → 거버넌스(키 상태, 예산, rate limit).

2.1 403 — Git remote is required. Please connect through SCC proxy to register your project.

• 원인: 요청에 X-Git-Remote 헤더가 없습니다(gateway 직접 호출, 또는 프록시가 remote를 확인하지 못함 — 위 섹션 참고). Admin이 키에 bypass_git_guard를 켜지 않은 한 gateway는 기본적으로 이 헤더를 요구합니다.
• 사용자 조치: gateway에 직접 호출하지 말고 sotatek-proxy를 통해 접속하세요. 저장소에서 sotatek-proxy doctor를 실행하세요.
• Admin/IT 문의: CI/스크립트용 bypass_git_guard가 필요하거나, 프록시가 정상인데도 오류가 계속될 때.

2.2 403 — Git remote is required. Invalid project context — please reconnect through SCC proxy.

• 원인: X-Git-Remote가 있지만 base64가 잘못되었거나 비어 있습니다.
• 사용자 조치: 프록시를 재시작(sotatek-proxy stop 후 start)하고 다른 도구가 이 헤더를 추가하지 않는지 확인하세요.
• 헤더는 유효하지만 내용에 사용할 수 있는 remote가 없는 경우는 거부되지 않으며, 요청에 프로젝트가 연결되지 않을 뿐입니다.

2.3 403 — this key's project does not match the calling project's git remote

• 원인: 저장소의 git remote가 Admin에 의해 프로젝트 A에 배정되었는데, 사용 중인 키는 프로젝트 B 소속입니다.
• 사용자 조치: 작업 중인 프로젝트의 키를 사용하거나 올바른 키를 요청하세요.
• Admin/IT 문의: 키가 맞는데도 오류가 계속되면 — 저장소가 잘못된 프로젝트에 배정되었거나 키의 태그가 잘못되었을 수 있습니다. 저장소에 프로젝트가 없거나 키에 프로젝트가 없으면 이 검사는 건너뜁니다.

2.4 403 — requested model is not permitted

• 원인: 저장소의 프로젝트에 허용 모델 목록이 있고 요청한 모델이 그 안에 없습니다. 메시지에는 의도적으로 프로젝트 이름이 없습니다.
• 사용자 조치: 모델을 변경하세요. Admin/IT가 프로젝트에 모델을 추가할 수 있습니다.

2.5 403 virtual_key_blocked — Virtual key is inactive

• 원인: Admin이 키를 비활성화했습니다.
• 먼저 확인하세요 — 잘못된 키를 보내고 있을 수 있습니다. Claude Code는 환경 변수와 ~/.claude/settings.json에서 키를 읽고, VS Code와 Antigravity에는 별도 설정이 있습니다. 이들 간의 충돌만으로 이 오류가 생기지는 않지만, 도구가 오래되었거나 비활성화된 키를 보내면 발생합니다. 확인할 항목:
  1. ~/.claude/settings.json의 env 섹션과 셸 환경 변수의 ANTHROPIC_AUTH_TOKEN.
  2. VS Code(VS Code)와 Antigravity(Antigravity)에 설정된 키.
  3. 유효한 키 하나로 통일한 뒤 CLI/IDE를 재시작.
• Admin/IT 문의: 보내는 키가 발급받은 키임이 확실한 경우.

2.6 403 virtual_key_blocked — Virtual key has expired / Virtual key is not yet active

현재 시각(UTC)이 키의 end_date를 지났거나 start_date 이전입니다. Admin/IT에 연장 또는 유효 기간 확인을 요청하세요.

2.7 403 virtual_key_not_found — Virtual key not found

키(sk-bf-...)가 존재하지 않습니다: 오타, 복사 시 잘림, 또는 삭제됨. 다시 정확히 복사하고, 그래도 안 되면 Admin/IT에 재발급을 요청하세요.

2.8 401 virtual_key_required

• 메시지: virtual key is required. Provide a virtual key via the x-bf-vk header.
• 원인: gateway가 virtual key를 필수로 요구하는데 요청에 유효한 키가 없습니다. 키는 x-bf-vk, Authorization: Bearer, x-api-key, x-goog-api-key에서 읽으며 반드시 sk-bf-로 시작해야 합니다. 다른 접두사의 키는 키가 없는 것으로 간주됩니다.
• 사용자 조치: ANTHROPIC_AUTH_TOKEN이 설정되어 있고 형식이 올바른지 확인하세요.

2.9 401 Unauthorized / invalid_admin_api_key / 403 forbidden_for_api_key_actor

일반 사용자에게는 드뭅니다. 보통 모델 호출 경로에 관리자 키(bfak_*)를 사용했거나 gateway가 추가 자격 증명을 요구하는 경우입니다. sk-bf-... virtual key를 사용하고, 그래도 안 되면 Admin/IT에 문의하세요.

2.10 403 model_blocked / provider_blocked

Model '<model>' is not allowed for this virtual key / Provider '<p>' is not allowed for this virtual key. 2.4와 달리 프로젝트가 아닌 키 기준 제한입니다. 모델/Provider를 바꾸거나 Admin/IT에 키의 허용 목록 변경을 요청하세요.

2.11 429 rate_limited / token_limited / request_limited

예: rate limit violated for <name>: [token limit exceeded (used/max, resets every <window>)]. 메시지에 적힌 초기화 시점까지 기다리고 호출 빈도를 줄이세요. 필요하면 Admin/IT에 한도 상향을 요청하세요.

2.12 402 budget_exceeded

<scope> budget exceeded: <used> >= <max> dollars (scope: 키, 팀, 고객, Provider 또는 모델). 직접 해결할 수 없습니다 — Admin/IT에 문의하거나 예산 주기가 초기화될 때까지 기다리세요.

2.13 429 user_budget_exceeded

user budget exceeded — contact administrator. 예산은 키 소유자 기준입니다. Admin/IT에 문의하거나 초기화를 기다리세요.

2.14 400 missing_required_headers

missing required headers: <list>. Admin이 필수 헤더를 설정한 경우에만 나타납니다. 어떤 헤더를 보내야 하는지 Admin/IT에 문의하세요.

3. Provider 오류

Provider의 4xx/5xx(잘못된 Provider 키, upstream rate limit, 5xx, 529 overloaded)는 gateway가 원본 메시지와 함께 전달하며, 대개 HTTP 상태도 그대로입니다. 429/5xx/529는 잠시 후 다시 시도하고, 계속되면 발생 시각과 함께 Admin/IT에 알려 주세요.

빠른 진단

1. HTTP 상태와 본문으로 프록시, gateway, Provider 오류를 구분합니다.
2. git 관련 403(2.1–2.3)은 오류가 나는 저장소에서 sotatek-proxy doctor를 실행합니다.
3. 키 오류(2.5–2.8)는 실제로 전송되는 키를 확인합니다(~/.claude/settings.json, 환경 변수, IDE 설정).
4. 그래도 불분명하면(예: 이 페이지에 없는 메시지의 403): Admin/IT에 발생 시각과 키의 마지막 8자를 보내세요. gateway 대시보드 로그에서 조회할 수 있습니다.