Na tej stronie znajdziesz rozwiązania typowych problemów z kodami błędów w pakietach SDK Gemini API i Firebase AI Logic.
Błąd 400: API key not valid. Please pass a valid API key.
Jeśli pojawi się błąd 400 z komunikatem API key not valid. Please pass a valid API key., zwykle oznacza to, że klucz interfejsu API w pliku lub obiekcie konfiguracji Firebase nie istnieje lub nie jest skonfigurowany do użycia z aplikacją lub projektem w Firebase.
Sprawdź, czy klucz interfejsu API podany w pliku/obiekcie konfiguracji Firebase jest zgodny z kluczem interfejsu API Twojej aplikacji. Wszystkie klucze interfejsu API możesz wyświetlić w panelu Interfejsy API i usługi > Dane logowania w konsoli Google Cloud.
Jeśli okaże się, że nie są zgodne, pobierz nowy plik lub obiekt konfiguracji Firebase, a następnie zastąp nim ten, który jest w aplikacji. Nowy plik lub obiekt konfiguracji powinien zawierać prawidłowy klucz interfejsu API dla aplikacji i projektu w Firebase.
Błąd 400: Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.
Jeśli spróbujesz wysłać żądanie multimodalne z adresem URL Cloud Storage for Firebase, może pojawić się ten błąd 400:
Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.
Ten błąd jest spowodowany przez projekt, który nie miał prawidłowo automatycznie udostępnionych wymaganych agentów usługi, gdy włączono w nim interfejs API Agent Platform. Jest to znany problem w przypadku niektórych projektów i pracujemy nad jego rozwiązaniem.
Oto obejście, które pozwoli Ci naprawić projekt i prawidłowo udostępnić te agenty usługi, aby można było zacząć uwzględniać adresy URL Cloud Storage for Firebase w żądaniach multimodalnych. Musisz być właścicielem projektu. Ten zestaw zadań musisz wykonać tylko raz w projekcie.
Uzyskaj dostęp i uwierzytelnij się za pomocą gcloud CLI.
Najłatwiej zrobić to w Cloud Shell. Więcej informacji znajdziesz w dokumentacji Google Cloud.Jeśli pojawi się taka prośba, postępuj zgodnie z instrukcjami wyświetlanymi w terminalu, aby uruchomić gcloud CLI w projekcie w Firebase.
Potrzebny będzie identyfikator projektu w Firebase, który znajdziesz u góry strony settings Ustawienia projektu w konsoli Firebase.
Uruchom to polecenie, aby udostępnić wymaganych agentów usługi w projekcie:
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 ''
Poczekaj kilka minut, aby upewnić się, że agenty usługi zostały udostępnione, a następnie spróbuj ponownie wysłać żądanie multimodalne zawierające adres URL Cloud Storage for Firebase.
Jeśli po kilku minutach nadal widzisz ten błąd, skontaktuj się z zespołem pomocy Firebase.
Błąd 403: PERMISSION_DENIED: To access this model, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check
Jeśli pojawi się błąd 403 - PERMISSION_DENIED z komunikatem To access this model, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check, oznacza to, że Twoje żądanie nie ma prawidłowego tokena App Check i próbujesz uzyskać dostęp do modelu, który jest często nadużywany.
Zidentyfikowano niektóre modele generatywne, które są często nadużywane przez nieuczciwe podmioty.
Bez App Check Twój projekt jest narażony na nadużycia związane z tymi modelami. Aby chronić naszych deweloperów, Firebase blokuje dostęp do tych modeli, chyba że żądania zawierają prawidłowy token App Check (co wymaga wymuszenia App Check w przypadku Firebase AI Logic).
Jeśli chcesz uzyskać dostęp do modelu, który zwrócił błąd, wykonaj te czynności:
Skonfiguruj App Check dla Firebase AI Logic. W przypadku programowania lokalnego skonfiguruj App Check dostawcę debugowania.
Jeśli usługa App Check jest już skonfigurowana, upewnij się, że wszystkie czynności opisane w instrukcjach, do których prowadzi link, zostały wykonane.
Ponownie wyślij prośbę z aplikacji do użytkownika Firebase AI Logic.
To żądanie wyśle prawidłowy token App Check i nie będziesz już otrzymywać błędu 403.
Błąd 403 nadal występuje?
Jeśli zasada App Check jest wymuszana i wysłano żądanie, ale nadal pojawia się błąd 403, sprawdź, czy ochrona przed powtórzeniem jest wymuszana w przypadku Firebase AI Logic (w tym w trybie „Tylko monitorowanie”).
Gdy ochrona przed powtórzeniem jest wymuszana, tylko tokeny o ograniczonym użyciu są uznawane za zweryfikowane w przypadku Firebase AI Logic, co oznacza, że zwykłe tokeny sesji nie mogą usunąć tego błędu 403. Aby rozwiązać ten problem, wykonaj jedną z tych czynności:
Opcja 1. Jeśli chcesz używać ochrony przed powtórzeniami, sprawdź jej konfigurację.
Upewnij się, że zostały wykonane wszystkie czynności związane z konfigurowaniem ochrony przed ponownym odtworzeniem, w tym włączenie tokenów o ograniczonym użyciu w bazie kodu aplikacji.
Wyślij ponownie prośbę do: Firebase AI Logic.
Opcja 2. Jeśli nie chcesz używać ochrony przed powtórzeniami lub nie masz włączonych tokenów o ograniczonym użyciu w aplikacji, możesz wyłączyć ochronę przed powtórzeniami.
Wyłącz wymuszanie ochrony przed powtórzeniami w konsoli Firebase: otwórz kartę Zabezpieczenia > Sprawdzanie aplikacji > Interfejsy API, kliknij, aby rozwinąć wiersz Firebase AI Logic, kliknij Skonfiguruj, a następnie w oknie dialogowym wyłącz wymuszanie ochrony przed powtórzeniami.
Wyślij ponownie prośbę do: Firebase AI Logic.
Zanim udostępnisz aplikację użytkownikom, musisz skonfigurować dostawcę atestów produkcyjnych (np. App Attest, Play Integrity lub reCAPTCHA Enterprise), aby użytkownicy mogli korzystać z funkcji AI, gdy wymuszane jest użycie App Check.
Błąd 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
Jeśli pojawi się błąd 403 - PERMISSION_DENIED o treści 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, oznacza to, że Twój projekt w Firebase został zidentyfikowany jako nieaktywny, a żądania z Twojej aplikacji nie mają prawidłowego tokena App Check.
„Nieaktywne projekty” to takie, które mają włączoną usługę Firebase AI Logic, ale nie były ostatnio używane w Firebase AI Logic.
Bez App Check Twój projekt jest narażony na nadużycia Gemini API. Aby chronić Twój projekt, Firebase wyłączył korzystanie z Firebase AI Logic, dopóki Twoje żądania nie będą zawierać prawidłowego tokena App Check (co wymaga wymuszenia App Check w przypadku Firebase AI Logic).
Gdy będziesz gotowy, aby ponownie zacząć korzystać z Firebase AI Logic, wykonaj te czynności:
Skonfiguruj App Check dla Firebase AI Logic. W przypadku programowania lokalnego skonfiguruj App Check dostawcę debugowania.
Jeśli usługa App Check jest już skonfigurowana, upewnij się, że wszystkie czynności opisane w instrukcjach, do których prowadzi link, zostały wykonane.
Ponownie wyślij prośbę z aplikacji do użytkownika Firebase AI Logic.
To żądanie wyśle prawidłowy token App Check i nie będziesz już otrzymywać błędu 403.
Błąd 403 nadal występuje?
Jeśli zasada App Check jest wymuszana i wysłano żądanie, ale nadal pojawia się błąd 403, sprawdź, czy ochrona przed powtórzeniem jest wymuszana w przypadku Firebase AI Logic (w tym w trybie „Tylko monitorowanie”).
Gdy ochrona przed powtórzeniem jest wymuszana, tylko tokeny o ograniczonym użyciu są uznawane za zweryfikowane w przypadku Firebase AI Logic, co oznacza, że zwykłe tokeny sesji nie mogą usunąć tego błędu 403. Aby rozwiązać ten problem, wykonaj jedną z tych czynności:
Opcja 1. Jeśli chcesz używać ochrony przed powtórzeniami, sprawdź jej konfigurację.
Upewnij się, że zostały wykonane wszystkie czynności związane z konfigurowaniem ochrony przed ponownym odtworzeniem, w tym włączenie tokenów o ograniczonym użyciu w bazie kodu aplikacji.
Wyślij ponownie prośbę do: Firebase AI Logic.
Opcja 2. Jeśli nie chcesz używać ochrony przed powtórzeniami lub nie masz włączonych tokenów o ograniczonym użyciu w aplikacji, możesz wyłączyć ochronę przed powtórzeniami.
Wyłącz wymuszanie ochrony przed powtórzeniami w konsoli Firebase: otwórz kartę Zabezpieczenia > Sprawdzanie aplikacji > Interfejsy API, kliknij, aby rozwinąć wiersz Firebase AI Logic, kliknij Skonfiguruj, a następnie w oknie dialogowym wyłącz wymuszanie ochrony przed powtórzeniami.
Wyślij ponownie prośbę do: Firebase AI Logic.
Zanim udostępnisz aplikację użytkownikom, musisz skonfigurować dostawcę atestów produkcyjnych (np. App Attest, Play Integrity lub reCAPTCHA Enterprise), aby użytkownicy mogli korzystać z funkcji AI, gdy wymuszane jest użycie App Check.
Błąd 403: PERMISSION_DENIED: The caller does not have permission.
Jeśli pojawi się błąd 403 z komunikatem PERMISSION_DENIED: The caller does not have permission., zwykle oznacza to, że klucz interfejsu API w pliku lub obiekcie konfiguracji Firebase należy do innego projektu w Firebase.
Sprawdź, czy klucz interfejsu API podany w pliku/obiekcie konfiguracji Firebase jest zgodny z kluczem interfejsu API Twojej aplikacji. Wszystkie klucze interfejsu API możesz wyświetlić w panelu Interfejsy API i usługi > Dane logowania w konsoli Google Cloud.
Jeśli okaże się, że nie są zgodne, pobierz nowy plik lub obiekt konfiguracji Firebase, a następnie zastąp nim ten, który jest w aplikacji. Nowy plik lub obiekt konfiguracji powinien zawierać prawidłowy klucz interfejsu API dla aplikacji i projektu w Firebase.
Błąd 403: Requests to this API firebasevertexai.googleapis.com ... are blocked.
Jeśli pojawi się błąd 403 z komunikatem Requests to this API firebasevertexai.googleapis.com ... are blocked., zwykle oznacza to, że klucz interfejsu API w konfiguracji Firebase w aplikacji ma ograniczenia, które uniemożliwiają mu wywołanie wymaganego interfejsu API.
Aby rozwiązać ten problem, musisz zaktualizować ograniczenia klucza interfejsu API w konsoli Google Cloud, aby uwzględnić wymagany interfejs API. W przypadku Firebase AI Logic musisz się upewnić, że interfejs Firebase AI Logic API (firebasevertexai.googleapis.com) znajduje się na liście wybranych interfejsów API, które można wywoływać za pomocą klucza interfejsu API.
Aby to zrobić:
W konsoli Google Cloud otwórz panel Interfejsy API i usługi > Dane logowania.
Wybierz klucz interfejsu API, którego ma używać Twoja aplikacja (np. „klucz iOS” w przypadku aplikacji na iOS).
Na stronie Edytuj klucz interfejsu API znajdź sekcję Ograniczenia interfejsów API.
Upewnij się, że wybrana jest opcja Ogranicz klucz. Jeśli nie, klucz nie jest ograniczony i prawdopodobnie nie jest to źródłem błędu.
W menu Wybrane interfejsy API wyszukaj i wybierz Firebase AI Logic API, aby dodać go do listy wybranych interfejsów API, które można wywoływać za pomocą klucza interfejsu API.
Kliknij Zapisz.
Zastosowanie zmian może potrwać do 5 minut.
Błąd 404: Firebase AI Logic genai config not found
Jeśli pojawi się błąd 404 z komunikatem Firebase AI Logic genai config not found, zwykle oznacza to, że ustawienie Firebase AI Logic jest nieprawidłowo skonfigurowane lub go brakuje.
Oto najbardziej prawdopodobne przyczyny tego błędu:
Nie masz jeszcze skonfigurowanego projektu w Firebase dla dostawcy Gemini API.
Co zrobić:
W konsoli Firebase otwórz Usługi AI > Logika AI. Kliknij Rozpocznij, a następnie wybierz dostawcę Gemini API. Włącz interfejs API, a Firebase skonfiguruje Twój projekt pod kątem tego dostawcy. Po zakończeniu procesu spróbuj ponownie wysłać prośbę.Jeśli niedawno przeprowadzono konfigurację Firebase AI Logic w konsoli Firebase, konfiguracja Firebase AI Logic może nie być jeszcze dostępna dla wszystkich wymaganych usług backendu we wszystkich odpowiednich regionach.
Co zrobić:
Poczekaj kilka minut i spróbuj ponownie.
Błąd 404: model „was not found or your project does not have access to it”?
Na przykład: „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.”
Ten błąd może wystąpić z kilku powodów.
Nieprawidłowa nazwa modelu
Przyczyna: podana nazwa modelu jest nieprawidłowa.
Rozwiązanie: sprawdź nazwę i wersję modelu na liście wszystkich obsługiwanych i dostępnych modeli. Sprawdź segmenty i ich kolejność w nazwie modelu. Na przykład:
- Nazwa najnowszego modelu Gemini 4 Hydrogen:
gemini-4-hydrogen - Nazwa najnowszego modelu Gemini 4 Argon:
gemini-4-argon - Nazwa najnowszego modelu Gemini 4 Carbon:
gemini-4-carbon - Nazwa najnowszego modelu Gemini 3.x Flash:
gemini-3.8-flash - Nazwa najnowszego modelu Gemini 3.x Flash‑Lite:
gemini-3.5-flash-lite - Nazwa najnowszego modelu Gemini Nano Banana 2.1:
gemini-nano-banana-2.1 - Nazwa najnowszego modelu Gemini Nano Banana 2:
gemini-3.1-flash-image - Nazwa najnowszego modelu Gemini Nano Banana 2 Lite:
gemini-3.1-flash-lite-image - Nazwa najnowszego modelu Gemini Nano Banana Pro:
gemini-3-pro-image
- Nazwa najnowszego modelu Gemini 4 Hydrogen:
Wyłączanie (wycofanego) modelu
Przyczyna: model, do którego próbujesz uzyskać dostęp, przekroczył datę wyłączenia (wycofania) i został trwale dezaktywowany (np. modele Gemini 2.5 ogólnego zastosowania w Agent Platform Gemini API (formerly Vertex AI), modele Gemini 2.0 lub modele Imagen).
Rozwiązanie: zapoznaj się z najczęstszymi pytaniami dotyczącymi wycofanych i wyłączonych modeli i zaktualizuj kod, aby używać aktywnego modelu zastępczego.
Nieprawidłowa lokalizacja (dotyczy tylko dostawcy Agent Platform Gemini API (formerly Vertex AI))
Przyczyna: Twoje żądanie może próbować uzyskać dostęp do modelu w lokalizacji, w której model nie jest dostępny.
Rozwiązanie: upewnij się, że żądanie próbuje uzyskać dostęp do modelu tam, gdzie jest on dostępny.
Podczas korzystania z Agent Platform Gemini API (formerly Vertex AI) możesz opcjonalnie określić lokalizację, aby uzyskać dostęp do modelu podczas inicjowania. Jeśli nie określisz lokalizacji, Firebase AI Logic domyślnie użyje tych lokalizacji:
- Jeśli używasz składni inicjowania „Agent Platform”:
global - Jeśli używasz starszej składni inicjowania „Vertex AI”:
us-central1
Jednak nie wszystkie modele są obsługiwane w tych domyślnych lokalizacjach. Oznacza to, że w zależności od modelu może być konieczne wyraźne ustawienie konkretnej lokalizacji podczas inicjowania.
Modele Gemini w wersji testowej i eksperymentalne: dostępne tylko w lokalizacji
global.Modele stabilne Gemini 4.x i Gemini 3.x: dostępne w lokalizacji
globali często w lokalizacjachusieu.Modele Gemini Live API 2.5: dostępne w wielu lokalizacjach, ale niedostępne w
global. (Pamiętaj, że modele Gemini 2.5 ogólnego zastosowania zostały wyłączone w Agent Platform Gemini API (formerly Vertex AI)).
- Jeśli używasz składni inicjowania „Agent Platform”:
Dowiedz się więcej o tym, jak określić lokalizację, w której model ma być dostępny (w tym fragmenty kodu).
Błędy 429: "You exceeded your current quota, please check your plan and billing details" lub "Resource exhausted, please try again later."
Ten błąd może wystąpić z kilku powodów.
Przekraczasz limit lub model, z którego korzystasz, jest przeciążony żądaniami od innych osób.
Działanie, które należy podjąć, zależy od tego, czy używasz Gemini Developer API czy Agent Platform Gemini API (formerly Vertex AI). Więcej informacji o limitach i o tym, jak poprosić o dodatkowy limit, znajdziesz w artykule Limity i limity żądań.
Jeśli używasz Agent Platform Gemini API (formerly Vertex AI), dokumentacja Google Cloud zawiera dodatkowe informacje i wskazówki dotyczące kodu błędu 429.
Próbujesz użyć modelu lub funkcji, które wymagają płatności, ale Twój projekt w Firebase jest objęty abonamentem Spark.
Jeśli korzystasz z Gemini Developer API, możesz uzyskać ograniczony dostęp do niektórych modeli i dostęp do wielu podstawowych funkcji w ramach Gemini Developer API „poziomu bezpłatnego”. Ten poziom pozwala rozpocząć korzystanie z usługi bez konieczności podawania formy płatności, co oznacza, że nie musisz przechodzić na abonament Blaze (płatność według wykorzystania) w projekcie w Firebase.
Niektóre modele nie są dostępne w Gemini Developer API „poziomie bezpłatnym” i wymagają „płatnego poziomu”, co oznacza, że Twój projekt musi być objęty abonamentem Blaze z płatnością według wykorzystania. Na przykład te modele prawie zawsze wymagają płatności:
- Większość modeli w wersji testowej i eksperymentalnej
- Modele generujące multimedia (takie jak modele Gemini Nano Banana)
Niektóre modele oferują podstawowe funkcje w ramach Gemini Developer API „poziomu bezpłatnego”, ale wymagają „poziomu płatnego”, aby można było korzystać z bardziej zaawansowanych funkcji. Na przykład:
- W przypadku większości modeli Gemini 3.x
grounding za pomocą
Google Search lubGoogle Maps wymaga rozliczeń.
- W przypadku większości modeli Gemini 3.x
grounding za pomocą
Dowiedz się więcej o abonamentach Firebase i Gemini Developer API.
Więcej informacji znajdziesz w Gemini Developer APIdokumentacji dotyczącej cen i najczęstszych pytaniach na temat płatności.