오류 코드

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.

이 오류는 프로젝트에서 Vertex AI API가 사용 설정되었을 때 필요한 서비스 에이전트가 올바르게 자동 프로비저닝되지 않아 발생합니다. 이는 일부 프로젝트에서 발생하는 알려진 문제이며, 현재 전역적으로 해결하기 위해 노력하고 있습니다.

프로젝트를 수정하고 이러한 서비스 에이전트를 올바르게 프로비저닝하여 멀티모달 요청에 Cloud Storage for Firebase URL을 포함할 수 있도록 하는 해결 방법은 다음과 같습니다. 프로젝트의 소유자여야 하며, 프로젝트에 대해 이 작업 세트를 한 번만 완료하면 됩니다.

1. gcloud CLI로 액세스하고 인증합니다.
   이 작업을 수행하는 가장 쉬운 방법은 Cloud Shell에서 하는 것입니다. Google Cloud 문서에서 자세히 알아보세요.

2. 메시지가 표시되면 터미널에 표시된 안내에 따라 gcloud CLI가 Firebase 프로젝트에 대해 실행되도록 합니다.

   Firebase 프로젝트 ID가 필요합니다. 이 ID는 Firebase Console의 settings 프로젝트 설정 상단에서 확인할 수 있습니다.

3. 다음 명령어를 실행하여 프로젝트에서 필요한 서비스 에이전트를 프로비저닝합니다.

   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 ''
   

4. 서비스 에이전트가 프로비저닝될 때까지 몇 분 정도 기다린 후 Cloud Storage for Firebase URL이 포함된 멀티모달 요청을 다시 전송합니다.

몇 분 정도 기다린 후에도 이 오류가 계속 발생하면 Firebase 지원팀에 문의하세요.

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의 경우 Firebase AI Logic API(firebasevertexai.googleapis.com)가 API 키를 사용하여 호출할 수 있는 선택된 API 목록에 포함되어 있어야 합니다.

다음 단계를 따르세요.

1. Google Cloud 콘솔에서 API 및 서비스 > 사용자 인증 정보 패널을 엽니다.

2. 애플리케이션에서 사용하도록 구성된 API 키를 선택합니다 (예: iOS 앱의 경우 'iOS 키').

3. API 키 수정 페이지에서 API 제한사항 섹션을 찾습니다.

4. 키 제한 옵션이 선택되어 있는지 확인합니다. 그렇지 않은 경우 키가 제한되지 않으며 오류의 원인이 아닐 가능성이 높습니다.

5. 선택한 API 드롭다운 메뉴에서 Firebase AI Logic API를 검색하여 선택한 API 목록에 추가합니다. 이 목록의 API는 API 키를 사용하여 호출할 수 있습니다.

6. 저장을 클릭합니다.

   변경사항이 적용되려면 최대 5분이 걸릴 수 있습니다.

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 키가 포함되어야 합니다.

404 오류: Firebase AI Logic genai config not found

Gemini Developer API를 사용하려고 할 때 Firebase AI Logic genai config not found라는 404 오류가 표시되면 일반적으로 Firebase 프로젝트에 Firebase AI Logic 클라이언트 SDK와 함께 사용할 수 있는 유효한 Gemini API 키가 없다는 의미입니다.

이 오류의 가장 가능성 높은 원인은 다음과 같습니다.

• 아직 Gemini Developer API에 대한 Firebase 프로젝트를 설정하지 않았습니다.

  해야 할 작업:
  Firebase 콘솔에서 Firebase AI Logic 페이지로 이동합니다. 시작하기를 클릭한 다음 Gemini Developer API를 선택합니다. API를 사용 설정하면 콘솔에서 Gemini Developer API용 프로젝트를 설정합니다. 워크플로를 완료한 후 요청을 다시 시도하세요.

• Firebase 콘솔에서 최근에 Firebase AI Logic 설정 워크플로를 진행한 경우 Gemini API 키가 아직 모든 리전의 필수 백엔드 서비스에서 사용 가능하지 않을 수 있습니다.

  해결 방법:
  몇 분 정도 기다린 후 다시 요청해 보세요.

• Firebase 프로젝트에서 Gemini API 키가 삭제되었을 수 있습니다.

  해야 할 일:
  Firebase AI Logic에서 사용하는 Gemini API 키를 변경하는 방법을 알아봅니다.

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-pro-image-preview was not found or your project does not have access to it. Please ensure you are using a valid model version.'입니다.

이와 같은 오류가 발생하는 데는 몇 가지 이유가 있습니다.

• 잘못된 모델 이름

  • 원인: 제공한 모델 이름이 유효한 모델 이름이 아닙니다.

  • 수정: 모델 이름과 모델 버전을 지원되고 사용 가능한 모델 목록과 비교합니다. 모델 이름에서 세그먼트와 순서를 확인하세요. 예를 들면 다음과 같습니다.

    • Gemini 3.1 Pro 미리보기 모델 이름은 gemini-3.1-pro-preview입니다.
    • Gemini 3 Flash 미리보기 모델 이름은 gemini-3-flash-preview입니다.
    • 'Nano Banana Pro' 미리보기 모델 이름은 gemini-3-pro-image-preview입니다.
    • 'Nano Banana 2' 미리보기 모델 이름은 gemini-3.1-flash-image-preview입니다.
    • 'Nano Banana' 모델 이름은 gemini-2.5-flash-image입니다.

• 잘못된 위치 (Vertex AI Gemini API 제공업체와 미리보기 또는 실험 모델을 사용하는 경우에만 적용됨)

  • 원인: 모델의 미리보기 또는 실험용 버전을 사용하고(예: gemini-3.1-pro-preview 및 gemini-3.1-flash-image-preview) global 위치를 지정하지 않았습니다.

    Vertex AI Gemini API를 사용하는 경우 모든 프리뷰 및 실험용 Gemini 모델 (Gemini Live 모델 제외)은 global 위치에서만 사용할 수 있습니다. 하지만 Firebase AI Logic는 기본적으로 us-central1 위치로 설정되므로 이러한 미리보기 및 실험용 Gemini 모델을 사용할 때는 코드에서 Vertex AI Gemini API 백엔드 서비스를 초기화할 때 global 위치를 명시적으로 지정해야 합니다.

  • 수정: Vertex AI Gemini API 서비스를 초기화할 때 위치 global를 지정합니다. 모델에 액세스할 위치를 지정하는 방법(코드 스니펫 포함)을 자세히 알아보세요.

• 잘못된 위치 (Vertex AI Gemini API 제공업체를 사용하는 경우에만 적용)

  • 원인: 액세스하려는 위치에서 지원되지 않는 모델을 사용하고 있습니다.

    Vertex AI Gemini API를 사용하는 경우 일부 모델은 특정 지역에서만 사용할 수 있습니다. 예 (일부만 제시)

    • Imagen 모델은 global 위치에서 지원되지 않습니다.
    • Gemini Live API 모델 (예: gemini-2.0-flash-live-preview-04-09)은 us-central1 위치에서만 지원됩니다.
    • Gemini 2.5 모델 (예: gemini-2.5-pro)은 global 위치, 미국 위치, 일부 유럽 위치에서만 사용할 수 있습니다(프로젝트에 특별 옵션이 있는 경우 다른 위치에서도 사용할 수 있음).

  • 수정: Vertex AI Gemini API 서비스를 초기화할 때 사용 중인 모델에 지원되는 위치를 지정해야 합니다. 모델에 액세스할 위치(코드 스니펫 포함)와 모델에 지원되는 위치를 지정하는 방법을 자세히 알아보세요.

    Firebase AI Logic은 기본적으로 us-central1 위치로 설정됩니다.

429 오류: "You exceeded your current quota, please check your plan and billing details" 또는 "Resource exhausted, please try again later."

429 오류는 할당량을 초과했거나 액세스하는 모델이 다른 사용자의 요청으로 인해 과부하되었음을 나타냅니다.

취해야 할 조치는 Gemini Developer API 또는 Vertex AI Gemini API 사용 여부에 따라 다릅니다. 할당량 및 추가 할당량 요청 방법에 대한 자세한 내용은 속도 제한 및 할당량을 참고하세요.

Vertex AI Gemini API를 사용하는 경우 Google Cloud 문서에서 오류 코드 429에 관한 추가 컨텍스트와 안내를 제공합니다.