이 페이지에서는 Gemini API 및 Firebase AI Logic SDK의 일반적인 오류 코드 문제 해결 방법을 설명합니다.
400 오류: API key not valid. Please pass a valid API key.
API key not valid. Please pass a valid API key.라는 400 오류가 표시되면 일반적으로 Firebase 구성 파일/객체의 API 키가 존재하지 않거나 앱 또는 Firebase 프로젝트에서 사용하도록 설정되지 않은 것입니다.
Firebase 구성 파일/객체에 나열된 API 키가 앱의 API 키와 일치하는지 확인합니다. Google Cloud 콘솔의 API 및 서비스 > 사용자 인증 정보 패널에서 모든 API 키를 볼 수 있습니다.
일치하지 않는 경우 새 Firebase 구성 파일/객체를 가져온 후 앱에 있는 파일을 교체합니다. 새 구성 파일/객체에는 앱 및 Firebase 프로젝트의 유효한 API 키가 포함되어야 합니다.
400 오류: Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.
Cloud Storage for Firebase URL을 사용하여 멀티모달 요청을 전송하려고 하면 다음 400 오류가 발생할 수 있습니다.
Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.
이 오류는 프로젝트에서 Agent Platform API가 사용 설정되었을 때 필요한 서비스 에이전트가 올바르게 자동 프로비저닝되지 않은 프로젝트로 인해 발생합니다. 이는 일부 프로젝트에서 발생하는 알려진 문제이며 전역 수정 작업을 진행 중입니다.
다음은 멀티모달 요청에 Cloud Storage for Firebase URL을 포함할 수 있도록 프로젝트를 수정하고 이러한 서비스 에이전트를 올바르게 프로비저닝하는 해결 방법입니다. 프로젝트의 소유자여야 하며 프로젝트에서 이 일련의 작업을 한 번만 완료하면 됩니다.
gcloud CLI에 액세스하고 인증합니다.
가장 쉬운 방법은 Cloud Shell에서 하는 것입니다. Google Cloud 문서에서 자세히 알아보세요.메시지가 표시되면 터미널에 표시된 안내에 따라 Firebase 프로젝트에 대해 gcloud CLI를 실행합니다.
Firebase Console의 settings 프로젝트 설정 상단에서 확인할 수 있는 Firebase 프로젝트 ID가 필요합니다.
다음 명령어를 실행하여 프로젝트에서 필요한 서비스 에이전트를 프로비저닝합니다.
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/endpoints -d ''
서비스 에이전트가 프로비저닝될 때까지 몇 분 정도 기다린 후 Cloud Storage for Firebase URL이 포함된 멀티모달 요청을 다시 전송합니다.
몇 분 정도 기다린 후에도 이 오류가 계속 발생하면 Firebase 지원팀에 문의하세요.
403 오류: PERMISSION_DENIED: To access this model, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check
To access this model, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check라는 403 - PERMISSION_DENIED 오류가 표시되면 요청에 유효한 App Check 토큰이 없고 일반적으로 악용되는 모델에 액세스하려고 한다는 의미입니다.
일부 생성 모델은 악의적인 행위자가 악용하는 것으로 확인되었습니다.
Firebase AI Logic에 App Check가 적용되지 않으므로 프로젝트가 이러한 모델의 악용에 취약합니다. 개발자를 보호하기 위해 Firebase는 요청에 유효한 App Check 토큰이 포함되지 않는 한 이러한 모델에 대한 액세스를 차단합니다. 즉, Firebase AI Logic에 App Check가 적용됩니다.
오류를 반환한 모델에 액세스하려면 다음을 수행합니다.
Firebase AI Logic에 App Check 설정하기 로컬 개발의 경우 App Check 디버그 프로바이더를 설정해야 합니다.
App Check를 적용하는 것은 Gemini API 및 Gemini 모델을 악용으로부터 보호하는 데 매우 중요하며, 이 오류를 해결하려면 적용해야 합니다.
앱에서 Firebase AI Logic에 요청을 다시 보냅니다.
이 요청은 유효한 App Check 토큰과 함께 전송되며 더 이상 이
403 - PERMISSION_DENIED오류가 발생하지 않습니다.앱을 최종 사용자에게 출시하기 전에 App Check가 시행될 때 최종 사용자가 AI 기능에 액세스할 수 있도록 프로덕션 증명 제공업체(예: App Attest, Play Integrity, reCAPTCHA Enterprise)를 설정해야 합니다.
403 오류: PERMISSION_DENIED: Firebase AI Logic has been deactivated in this project. To resume using Firebase AI Logic, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check
Firebase AI Logic has been deactivated in this project. To resume using
Firebase AI Logic, you must enforce Firebase App Check. Learn more:
https://firebase.google.com/docs/ai-logic/app-check라는 403 - PERMISSION_DENIED 오류가 표시되면 Firebase 프로젝트가 비활성 상태로 식별되었으며 Firebase AI Logic에 App Check가 적용되지 않은 것입니다.
'비활성 프로젝트'는 Firebase AI Logic가 사용 설정되어 있지만 최근에 Firebase AI Logic를 사용하지 않은 프로젝트입니다.
Firebase AI Logic에 App Check가 적용되지 않으므로 프로젝트가 Gemini API 악용에 취약합니다. 프로젝트를 보호하기 위해 Firebase는 Firebase AI Logic에 App Check를 적용할 때까지 Firebase AI Logic 사용을 비활성화했습니다.
Firebase AI Logic를 다시 사용할 준비가 되면 다음을 수행합니다.
Firebase AI Logic에 App Check 설정하기 로컬 개발의 경우 App Check 디버그 프로바이더를 설정해야 합니다.
App Check를 적용하는 것은 Gemini API 및 Gemini 모델을 악용으로부터 보호하는 데 매우 중요하며, 이 오류를 해결하려면 적용해야 합니다.
앱에서 Firebase AI Logic에 요청을 다시 보냅니다.
이 요청은 유효한 App Check 토큰과 함께 전송되며 더 이상 이
403 - PERMISSION_DENIED오류가 발생하지 않습니다.이미 App Check를 시행하고 있는데도 이 오류가 계속 발생하면 Firebase AI Logic에 재전송 방지가 사용 설정되어 있는지 확인하세요('모니터링 전용' 모드 포함).
재생 보호가 사용 설정된 경우 Firebase AI Logic에 대해 일회용 토큰만 확인된 것으로 간주되며 일반 세션 토큰은 이 오류를 해결하지 않습니다. 앱에서 일회용 토큰을 사용 설정하거나 Firebase AI Logic에 대해 재생 보호를 사용 중지하고 요청을 다시 보낸 후 약 하루 동안 기다렸다가 재생 보호를 다시 사용 설정합니다 (프로젝트 활동은 매일 재평가됨).
앱을 최종 사용자에게 출시하기 전에 App Check가 시행될 때 최종 사용자가 AI 기능에 액세스할 수 있도록 프로덕션 증명 제공업체(예: App Attest, Play Integrity, reCAPTCHA Enterprise)를 설정해야 합니다.
403 오류: PERMISSION_DENIED: The caller does not have permission.
PERMISSION_DENIED: The caller does not have permission.라는 403 오류가 표시되면 일반적으로 Firebase 구성 파일/객체의 API 키가 다른 Firebase 프로젝트에 속해 있음을 의미합니다.
Firebase 구성 파일/객체에 나열된 API 키가 앱의 API 키와 일치하는지 확인합니다. Google Cloud 콘솔의 API 및 서비스 > 사용자 인증 정보 패널에서 모든 API 키를 볼 수 있습니다.
일치하지 않는 경우 새 Firebase 구성 파일/객체를 가져온 후 앱에 있는 파일을 교체합니다. 새 구성 파일/객체에는 앱 및 Firebase 프로젝트의 유효한 API 키가 포함되어야 합니다.
403 오류: Requests to this API firebasevertexai.googleapis.com ... are blocked.
Requests to this API firebasevertexai.googleapis.com ... are blocked.라는 403 오류가 표시되면 일반적으로 앱의 Firebase 구성에 있는 API 키에 필수 API를 호출하지 못하도록 하는 제한사항이 있음을 의미합니다.
이 문제를 해결하려면 Google Cloud 콘솔에서 API 키의 제한사항을 업데이트하여 필요한 API를 포함해야 합니다. Firebase AI Logic의 경우 API 키를 사용하여 호출할 수 있는 선택된 API 목록에 Firebase AI Logic API(firebasevertexai.googleapis.com)가 포함되어 있는지 확인해야 합니다.
다음 단계를 따르세요.
Google Cloud 콘솔에서 API 및 서비스 > 사용자 인증 정보 패널을 엽니다.
애플리케이션에서 사용하도록 구성된 API 키를 선택합니다 (예: iOS 앱의 'iOS 키').
API 키 수정 페이지에서 API 제한사항 섹션을 찾습니다.
키 제한 옵션이 선택되어 있는지 확인합니다. 그렇지 않으면 키가 제한되지 않으며 오류의 원인이 아닐 수 있습니다.
선택한 API 드롭다운 메뉴에서 Firebase AI Logic API를 검색하고 선택하여 API 키를 사용하여 호출할 수 있는 선택한 API 목록에 추가합니다.
저장을 클릭합니다.
변경사항이 적용되는 데 최대 5분이 걸릴 수 있습니다.
404 오류: Firebase AI Logic genai config not found
Firebase AI Logic genai config not found라는 404 오류가 표시되면 일반적으로 Firebase AI Logic 설정이 잘못 구성되었거나 누락된 것입니다.
이 오류의 가장 일반적인 원인은 다음과 같습니다.
아직 Gemini API 제공업체에 Firebase 프로젝트를 설정하지 않았습니다.
수행할 작업:
Firebase 콘솔에서 AI 서비스 > AI 로직으로 이동합니다. 시작하기를 클릭한 후 선택한 Gemini API 제공업체를 선택합니다. API를 사용 설정하면 Firebase가 해당 제공업체에 맞게 프로젝트를 설정합니다. 워크플로를 완료한 후 요청을 다시 시도합니다.최근에 Firebase 콘솔에서 Firebase AI Logic 설정 워크플로를 진행한 경우 모든 관련 리전의 모든 필수 백엔드 서비스에서 Firebase AI Logic 구성을 아직 사용하지 못할 수 있습니다.
해결 방법:
몇 분 정도 기다린 후 다시 요청을 시도하세요.
404 오류: 'was not found or your project does not have access to it' 모델
예를 들면 'Publisher Model projects/PROJECT-ID/locations/us-central1/publishers/google/models/gemini-3.1-pro-preview was not found or your project does not have access to it. Please ensure you are using a valid model version.'입니다.
이러한 오류가 발생하는 이유는 몇 가지가 있습니다.
모델 이름이 잘못되었습니다.
원인: 제공한 모델 이름이 유효한 모델 이름이 아닙니다.
수정: 지원되는 모든 사용 가능한 모델 목록에서 모델 이름과 모델 버전을 확인합니다. 모델 이름의 세그먼트와 순서를 확인하세요. 예를 들면 다음과 같습니다.
- 최신 Gemini 4 Argon
모델 이름:
gemini-4-argon - 최신 Gemini 3.x Pro 모델 이름:
gemini-3.1-pro-preview(프리뷰에서만 사용 가능) - 최신 Gemini 3.x Flash
모델 이름:
gemini-3.8-flash - 최신 Gemini 3.x Flash‑Lite
모델 이름:
gemini-3.5-flash-lite - 최신 Gemini Nano Banana 2.1
모델 이름:
gemini-nano-banana-2.1 - 최신 Gemini Nano Banana 2
모델 이름:
gemini-3.1-flash-image - 최신 Gemini Nano Banana 2 Lite
모델 이름:
gemini-3.1-flash-lite-image - 최신 Gemini Nano Banana Pro
모델 이름:
gemini-3-pro-image
- 최신 Gemini 4 Argon
모델 이름:
잘못된 위치 (Agent Platform Gemini API (formerly Vertex AI) 제공업체를 사용하는 경우에만 적용됨)
원인: 요청이 모델을 사용할 수 없는 위치에서 모델에 액세스하려고 시도할 수 있습니다.
해결 방법: 요청이 모델을 사용할 수 있는 위치에서 모델에 액세스하려고 하는지 확인합니다.
Agent Platform Gemini API (formerly Vertex AI)를 사용할 때 초기화 중에 모델에 액세스할 위치를 지정할 수 있습니다. 위치를 지정하지 않으면 Firebase AI Logic는 기본적으로 다음 위치로 설정됩니다.
- 'Agent Platform' 초기화 구문을 사용하는 경우:
global - 기존 'Vertex AI' 초기화 문법을 사용하는 경우:
us-central1
하지만 이러한 기본 위치에서 모든 모델이 지원되는 것은 아닙니다. 즉, 모델에 따라 초기화 중에 특정 위치를 명시적으로 설정해야 할 수 있습니다.
Gemini 프리뷰 및 실험 모델:
global위치에서만 사용할 수 있습니다.Gemini 4.x 및 Gemini 3.x 안정화 버전 모델:
global위치에서 사용할 수 있으며us및eu위치에서도 사용할 수 있는 경우가 많습니다.Gemini 2.5 모델: 여러 위치에서 사용 가능. Gemini Live API 2.5 모델은
global에서 사용할 수 없습니다.
- 'Agent Platform' 초기화 구문을 사용하는 경우:
모델에 액세스할 위치를 지정하는 방법(코드 스니펫 포함)을 자세히 알아보세요.
429 오류: "You exceeded your current quota, please check your plan and billing details" 또는 "Resource exhausted, please try again later."
이러한 오류가 발생하는 이유는 몇 가지가 있습니다.
할당량을 초과했거나 액세스 중인 모델이 다른 사용자의 요청으로 인해 과부하 상태입니다.
취해야 할 조치는 Gemini Developer API 또는 Agent Platform Gemini API (formerly Vertex AI) 사용 여부에 따라 다릅니다. 할당량 및 추가 할당량을 요청하는 방법에 대한 자세한 내용은 비율 제한 및 할당량을 참조하세요.
Agent Platform Gemini API (formerly Vertex AI)를 사용하는 경우 Google Cloud 문서에서 오류 코드 429에 대한 추가 컨텍스트와 안내를 제공합니다.
결제가 필요한 모델 또는 기능을 사용하려고 하지만 Firebase 프로젝트가 Spark 요금제에 있습니다.
Gemini Developer API를 사용하는 경우 Gemini Developer API '무료 등급'에서 특정 모델에 대한 제한된 액세스 권한과 많은 기본 기능에 대한 액세스 권한을 얻을 수 있습니다. 이 등급을 사용하면 결제 수단을 제공하지 않고도 시작할 수 있으므로 Firebase 프로젝트를 사용한 만큼만 지불하는 Blaze 요금제로 업그레이드할 필요가 없습니다.
일부 모델은 Gemini Developer API '무료 등급'에서 사용할 수 없으며 '유료 등급'이 필요합니다. 즉, 프로젝트에서 사용한 만큼만 지불하는 Blaze 요금제를 사용해야 합니다. 예를 들어 다음 모델은 거의 항상 결제가 필요합니다.
- 대부분의 프리뷰 및 실험 모델
- 미디어 생성 모델 (예: Gemini Nano Banana 모델)
일부 모델은 Gemini Developer API '무료 등급'에서 일부 기본 기능을 제공하지만 더 고급 기능을 사용하려면 '유료 등급'이 필요합니다. 예를 들면 다음과 같습니다.
- 대부분의 Gemini 3.x 모델을 사용할 때
Google Search 또는Google Maps 를 사용한 그라운딩에는 결제가 필요합니다.
- 대부분의 Gemini 3.x 모델을 사용할 때
Firebase 요금제 및 Gemini Developer API에 대해 알아보세요.