OpenAI Adapter - Gemini API 오류
API Key 있으면 되는줄 알았다 뜬 401 Authentication
들어가며
회사에서 LLM 관리를 위해 OpenAI Adapter 패턴을 도입했다. 다양한 모델을 통일된 인터페이스로 관리하기 위해서였다. Gemini API도 OpenAI 호환 엔드포인트를 제공하니까, API Key만 발급받으면 바로 연동될 거라 생각했다.
그런데 Tier 3(고수준 할당량) 프로젝트를 사용하려 하자 예상치 못한 에러가 터졌다.
401 UNAUTHENTICATED: API keys are not supported by this API.
Expected OAuth2 access token or other authentication credentials that assert a principal.
이 문제를 해결하며 얻은 교훈을 정리한다. 구글링해보니 나만 겪은 게 아니었다.
1. 같은 Gemini, 완전히 다른 두 세계
AI Studio vs. Vertex AI
[출처: Google AI Studio vs Vertex AI]
핵심: 같은 Gemini 모델을 쓰더라도 어떤 플랫폼으로 접근하느냐에 따라 인증 방식이 완전히 달라진다.
Tier 3처럼 결제 계정이 연결된 고급 프로젝트는 Vertex AI 보안 게이트웨이를 거친다. 이 게이트웨이는 단순 API Key를 거부하고 OAuth2 토큰을 요구한다.
[출처: GitHub Issue #5206 - "isVertex 파라미터가 true로 하드코딩되어 401 에러 발생"]
2. API Key는 "장기 비밀번호", Access Token은 "일회용 출입증"
인증 수단의 계층 구조
Google Cloud 공식 문서는 이렇게 말한다:
"서비스 계정 키를 사용하여 JWT에 서명하고 액세스 토큰으로 교환하는 것은 가능하지만, 보안상 서비스 계정 키보다 더 안전한 대안을 선택하는 것이 좋습니다."
[출처: Service account credentials | IAM]
왜 Access Token을 권장할까?
API Key: 탈취되면 만료 전까지 무제한 사용 가능
Access Token: 1시간 후 자동 만료, 탈취 피해 최소화
Tier 3 같은 고급 프로젝트에서 API Key를 거부하는 건 "보안 강화" 정책의 일환이다.
[출처: Create short-lived credentials]
3. OpenAI Adapter의 숨은 함정
같은 Bearer 형식, 다른 내용물
OpenAI 라이브러리를 Gemini와 연동할 때 흔한 실수:
[출처: OpenAI compatibility | Vertex AI]
문제의 핵심: Authorization: Bearer <값> 형식은 동일하지만, <값> 자리에 API Key를 넣느냐 Access Token을 넣느냐가 완전히 다른 결과를 만든다.
GitHub에서도 비슷한 사례가 다수 보고되었다:
"Open WebUI가 Gemini API를 OpenAI 호환 엔드포인트로 처리하지만, Bearer 토큰 전송 시 손상되거나 누락되는 경우가 발생한다. curl 직접 호출은 성공하지만 앱에서는 403 에러가 뜬다."
[출처: GitHub Issue #17403]
4. 인증(Authentication) vs. 인가(Authorization)
토큰을 성공적으로 생성해도 끝이 아니다.
IAM 역할 설정
서비스 계정에 반드시 부여해야 할 역할:
Vertex AI User (roles/aiplatform.user)
필요 권한: aiplatform.endpoints.predict
[출처: Vertex AI IAM permissions]
실제 개발자 포럼에 올라온 사례:
"서비스 계정에 Vertex AI User 역할을 부여했는데도 403 에러가 계속 떴다. 알고 보니 프로젝트 ID가 불일치했다."
[출처: Google Developer Forums]
5. 스코프(Scope) 설정의 Best Practice
Google Cloud 공식 가이드:
"Best practice는 cloud-platform 스코프를 설정하고, 서비스 계정의 접근을 IAM 역할로 제어하는 것이다. 스코프와 IAM 둘 다 허용해야 리소스에 접근할 수 있다."
[출처: Service accounts | Compute Engine]
6. 그 외 체크리스트
API 호출 전 확인 사항
파라미터 유효성: max_completion_tokens에 비현실적인 값(예: 100만) 입력 시 요청 거부
지역 제한: EEA/스위스/영국에서는 무료 티어 사용 불가, 결제 계정 필요
문서와 실제 동작 불일치: 공식 문서에 API Key 지원이라 적혀있어도 실제로는 거부되는 경우가 있다. 문서를 맹신하지 말고 실제 테스트 결과를 우선시하자.
[출처: Gemini API Error 401 Troubleshooting Guide, GitHub Issue #5739]
해결 플로우 요약
마치며
"보안은 때로 번거롭지만, 우리 프로젝트의 안전을 지키는 가장 확실한 장치입니다."
OpenAI Adapter로 여러 LLM을 관리하는 건 좋은 패턴이다. 하지만 각 제공사의 인증 정책이 다르다는 걸 간과하면 안 된다.
특히 Gemini는:
어떤 플랫폼(AI Studio vs Vertex AI)으로 접근하느냐
어떤 티어(무료 vs 유료)의 프로젝트인가
어떤 엔드포인트(네이티브 vs OpenAI 호환)를 쓰느냐
에 따라 인증 요구사항이 완전히 달라진다.
JSON 키 발급 → 토큰 생성 → 헤더 주입 파이프라인을 자동화해두면, 이런 인증 지옥에서 벗어날 수 있다.
참고 자료
공식 문서
OpenAI compatibility | Gemini API
OpenAI compatibility | Vertex AI
Service account credentials | IAM
커뮤니티 사례
- cline/cline #5206 - Vertex AI 엔드포인트 강제 사용으로 인한 401 에러
- google-gemini/gemini-cli #5739 - 문서와 실제 동작 불일치
- googleapis/python-genai #1404 - SDK에서 API Key 거부
- open-webui/open-webui #17403 - OpenAI 호환 연동 시 인증 실패
