제미나이 API 키가 안 될 때 — 제한 없는 키는 지금 거부됩니다
제한을 걸지 않은 표준 키(Unrestricted)는 지금 제미나이 API가 거부합니다. Google AI Studio의 API Keys 페이지에서 그 키에 Add restrictions → Restrict to Gemini API only 로 제한을 걸거나, 새 키(auth 키)를 만들어 바꾸면 됩니다. 아래는 내 키가 여기에 해당하는지 확인하는 법과 두 방법의 순서입니다.
한 줄 요약
키를 받은 지 오래됐고 제한을 건 적이 없다면, 그 키는 지금 거부됩니다. 구글 공식 문서의 문장 그대로 옮기면 "제미나이 API는 제한을 걸지 않은 표준 키의 요청을 거부한다", 그리고 "명시적 제한이 걸린 표준 키는 계속 작동한다"입니다.
고치는 길은 둘입니다. ① 지금 키에 제한을 건다(키 값이 그대로라 앱을 안 고쳐도 됨), ② 새 키를 만들어 바꾼다(지금 새로 만드는 키는 처음부터 제미나이 API로 제한된 auth 키). 키를 처음 받는 방법은 제미나이 API 키 발급방법에 따로 정리해 뒀습니다.
내 키가 막혔는지 어떻게 확인하나요?
AI Studio의 API Keys 페이지에서 키 옆에 붙은 표시를 봅니다. 오류 문구보다 이쪽이 정확합니다.
| 보이는 표시 | 뜻 | 할 일 |
|---|---|---|
| Unrestricted 라벨 | 제한을 걸지 않은 표준 키. 제미나이 API가 요청을 거부하는 대상 | 제한을 걸거나(방법 1) 새 키로 교체(방법 2) |
| Blocked 태그 | 오랫동안 쓰지 않아 차단된 제한 없는 키 | 새 키로 교체(방법 2) |
| 표시 없음 / 제한 걸린 표준 키 | 명시적 제한이 걸린 표준 키는 계속 작동 | 키 정책 문제가 아님 — 아래 「오류 메시지」 절로 |
공식 문서에 날짜가 붙은 변경은 두 가지입니다.
- 2026년 5월 7일부터 — 오랫동안 쓰지 않은 제한 없는 키를 차단하고, AI Studio에 Blocked 태그를 붙입니다. "오랫동안"이 며칠인지는 문서에 없습니다.
- 2026년 5월 28일부터 — Google AI Studio에서 새로 만드는 모든 키는 자동으로 auth 키(authorization key)로 만들어집니다.
"제한 없는 키를 언제부터 전부 거부했느냐"에 대해서는 공식 문서에 날짜가 적혀 있지 않습니다. 문서는 현재형으로 "거부한다"고만 씁니다. 그래서 이 글도 날짜를 못 박지 않고 "지금 거부된다"로만 적습니다.
두 종류의 키가 어떻게 다른지도 짧게 짚어 둡니다. 공식 문서의 설명입니다.
| 종류 | 공식 문서의 설명 |
|---|---|
| 표준 키 Standard | 요청을 구글 클라우드 프로젝트에 연결해 과금·할당량을 매기는 용도. 호출자가 누구인지는 특정하지 못함 |
| auth 키 Authorization | 클라우드 서비스 계정에 직접 묶임. 기본으로 Generative Language API(제미나이 API)로만 제한되고, 유출된 키를 빠르게 막는 장치가 있음. 단 auth 키로 보낸 요청은 서비스 계정 사용량 지표에 기록되지 않음 |
방법 1: 지금 키에 제한을 거는 법은?
키 값이 바뀌지 않으니 앱 설정을 손댈 필요가 없습니다. 쓰던 키가 Unrestricted 로 떠 있고 Blocked 태그는 없을 때 가장 빠른 방법입니다. AI Studio에서 네 단계입니다.
| 단계 | 할 일 |
|---|---|
| 1 | AI Studio API Keys 페이지에서 Unrestricted 라벨이 붙은 키를 찾는다 |
| 2 | 라벨에 마우스를 올리고, 뜨는 창에서 Add restrictions 를 누른다 |
| 3 | Restrict to Gemini API only 를 고른다 |
| 4 | Restrict key 를 눌러 확정한다 |
apikeys.keys.update 권한이 있어야 한다고 적습니다.
회사·학교 프로젝트라면 관리자에게 권한을 받거나, 권한이 있는 프로젝트에서 방법 2로 새 키를 만드세요.
더 단단히 막고 싶다면 구글 클라우드 콘솔에서 IP 제한을 추가로 걸 수 있습니다. 키의 Application restrictions 에서 IP addresses 를 고르고, 허용할 IP 주소나 대역을 적은 뒤 Save 를 누릅니다. 서버 한 곳에서만 호출한다면 쓸 만한 장치입니다.
한 가지 주의할 점이 있습니다. 지도(Maps) 같은 다른 구글 서비스용으로 만든 키를 제미나이에 같이 쓰지 마세요. 공식 문서는 다른 API용으로 키를 제한할 때 Generative Language API를 고르지 말라고 안내하고, 그렇게 제한된 키로 보낸 제미나이 요청은 실패한다고 적습니다. 제미나이용 키는 따로 두는 게 맞습니다.
참고로 Blocked 태그가 붙은 키에 제한을 걸면 다시 살아나는지는 공식 문서에 나와 있지 않습니다. 그 경우는 방법 2로 가는 편이 확실합니다.
방법 2: 새 auth 키로 바꾸려면?
기존 키를 auth 키로 "변환"하는 기능은 공식 문서에 없습니다. 문서가 안내하는 길은 새 auth 키를 만들고 앱을 그 키로 바꾸는 것입니다. 2026년 5월 28일 이후 AI Studio에서 만드는 키는 자동으로 auth 키라서, 지금 Create API key 를 누르면 됩니다.
| 단계 | 할 일 |
|---|---|
| 1 | AI Studio API Keys 페이지에서 Create API key 로 새 키를 만든다 |
| 2 | 코드·환경변수(GEMINI_API_KEY)·배포 설정의 키를 새 키로 바꾼다 |
| 3 | 새 키로 실제 호출이 되는지 확인한다 |
| 4 | 그다음에 옛 키를 삭제한다 |
auth 키는 처음부터 제미나이 API로만 제한돼 있어서, 방법 1의 제한 걸기를 따로 할 필요가 없습니다. 한 가지 차이는 알아 두세요 — 공식 문서는 auth 키로 보낸 요청이 서비스 계정 사용량 지표에 기록되지 않는다고 적습니다. 사용량을 그 지표로 보고 있었다면 확인 방법을 바꿔야 합니다.
오류 메시지로 구분할 수 있나요?
정직하게 말하면, 오류 문구만으로는 단정할 수 없습니다. 2026년 10월 8일 확인한 공식 문서(API 키·오류 코드·문제 해결 세 문서)에는 "제한 없는 키라서 거부됐다"는 전용 오류 문구나 HTTP 코드가 적혀 있지 않습니다. 인터넷에 "이 문구가 나오면 제한 없는 키"라고 적힌 글이 있다면 공식 근거는 없는 셈입니다.
공식 문서에 적힌 문구는 아래뿐입니다. 키와 관련해 볼 만한 것만 추렸습니다.
| 코드 | 상태 | 공식 문서의 설명 (원문) |
|---|---|---|
| 401 | authentication | The API key is missing, invalid, or expired. (키가 없거나, 무효이거나, 만료됨) |
| 403 | permission_denied | Your API key does not have permission for this resource. (이 리소스에 대한 권한이 없음) |
| — | 유출 신고 | Your API key was reported as leaked. Please use another API key. (키가 유출된 것으로 신고됨, 다른 키를 쓸 것) |
그래서 순서는 이렇게 잡는 게 맞습니다. 401·403이 나오면 먼저 AI Studio에서 그 키에 Unrestricted 라벨이나 Blocked 태그가 있는지 봅니다. 있으면 위의 방법 1·2로, 없으면 키 값 오타·환경변수 미반영·프로젝트 권한 같은 일반 원인을 봅니다. 일반 원인별 조치는 발급 가이드의 「막히면 여기부터」 표에 정리돼 있습니다. "reported as leaked" 문구가 나왔다면 다음 절의 순서를 그대로 따르세요.
키가 노출됐다면 어떤 순서로 하나요?
새 키부터 만들고, 옛 키는 맨 나중에 끕니다. 순서를 바꾸면 그 사이에 서비스가 멈춥니다. 공식 문서가 안내하는 순서입니다.
| 단계 | 할 일 |
|---|---|
| 1 | 새 키 생성 |
| 2 | 앱을 새 키로 갱신 |
| 3 | 새 키가 동작하는 것을 확인한 뒤, 클라우드 콘솔에서 유출된 키를 비활성화. 새 키가 완전히 활성화되기 전에는 옛 키를 지우지 않는다 |
| 4 | 청구 로그와 API 사용량 점검 — 남이 쓴 흔적이 있는지 본다 |
다시 새지 않게 하는 원칙도 공식 문서에 적혀 있습니다.
- 키를 비밀번호처럼 다룹니다.
- 깃(Git) 같은 소스 관리 시스템에 키를 올리지 않습니다.
- 운영 환경에서 키를 클라이언트(웹·앱) 쪽에 노출하지 않습니다. 서버에서 호출합니다.
auth 키는 유출된 키를 빠르게 막는 장치가 기본으로 붙어 있다는 점도 새 키로 옮길 이유가 됩니다.
이 글을 쓰면서
"제미나이 API 키 안됨"으로 찾아오는 분이 가장 먼저 알고 싶은 건 "내 키가 막힌 건가, 내가 뭘 잘못한 건가"일 겁니다. 그런데 공식 문서 세 개를 대조해 보니 제한 없는 키에만 나오는 오류 문구는 어디에도 없었습니다. 그래서 이 글은 오류 문구 대신 AI Studio의 Unrestricted 라벨과 Blocked 태그를 판단 기준으로 삼았습니다.
날짜도 같은 원칙으로 적었습니다. 공식 문서에 있는 날짜는 5월 7일과 5월 28일 두 개뿐이고, "전면 거부"가 언제 시작됐는지는 적혀 있지 않습니다. 근거 없는 날짜를 붙이지 않았습니다.
다른 API 키도 함께 정리하고 있다면 API 키 발급 연재와 유튜브 API 키 발급방법을, API 글 전체는 API 글 모음을 보시면 됩니다.
자주 묻는 질문
2026년 10월 8일 구글 공식 문서 확인 기준입니다.
제미나이 API 키가 갑자기 안 되는 이유는 무엇인가요?
제한을 걸지 않은 표준 키라면 그게 원인일 가능성이 큽니다. 구글 공식 문서는 제미나이 API가 제한 없는 표준 키의 요청을 거부한다고 적고 있습니다. AI Studio에서 그 키에 Restrict to Gemini API only 제한을 걸거나, 새 키를 만들어 바꾸면 됩니다.
AI Studio에서 키에 Blocked 태그가 붙어 있습니다. 무슨 뜻인가요?
2026년 5월 7일부터 제미나이 API는 오랫동안 쓰지 않은 제한 없는 키를 차단하고, 이런 키에 Blocked 태그를 붙입니다. 얼마나 안 써야 차단되는지 기준 기간은 공식 문서에 나와 있지 않습니다. 새 키를 만들어 앱에 넣는 것이 가장 확실합니다.
제한을 건 표준 키는 계속 쓸 수 있나요?
쓸 수 있습니다. 공식 문서는 명시적 제한이 걸린 표준 키는 계속 작동한다고 적고 있습니다. 거부되는 것은 제한을 걸지 않은 표준 키입니다.
기존 키를 auth 키로 바꿀 수 있나요?
공식 문서에는 기존 키를 auth 키로 바꾸는 기능이 없습니다. 새 auth 키를 만들어 앱의 키를 교체하고, 새 키가 잘 도는 것을 확인한 뒤 옛 키를 지우는 순서로 안내합니다. 2026년 5월 28일부터 AI Studio에서 새로 만드는 키는 자동으로 auth 키입니다.
제한 없는 키를 쓰면 어떤 오류 메시지가 나오나요?
2026년 10월 8일 확인한 공식 문서에는 제한 없는 키 전용 오류 문구나 HTTP 코드가 적혀 있지 않습니다. 오류 문서에 있는 것은 키가 없거나 무효·만료일 때의 401과 권한이 없을 때의 403이고, 유출 신고된 키는 Your API key was reported as leaked 라는 문구가 따로 있습니다. 오류 문구만으로 단정하지 말고 AI Studio에서 키 상태를 직접 확인하는 편이 정확합니다.
제한을 걸려는데 권한이 없다고 나옵니다.
키에 제한을 걸려면 그 키가 속한 구글 클라우드 프로젝트에 apikeys.keys.update 권한이 있어야 합니다. 회사나 학교 프로젝트라면 관리자에게 권한을 받거나, 권한이 있는 프로젝트에서 새 키를 만들어야 합니다.