На этой странице приведены инструкции по устранению неполадок, связанных с распространенными кодами ошибок в SDK Gemini API и Firebase AI Logic.
Ошибка 400: API key not valid. Please pass a valid API key.
Если вы получаете ошибку 400 с сообщением API key not valid. Please pass a valid API key., это обычно означает, что ключ API в файле или объекте конфигурации Firebase не существует или не настроен для использования с вашим приложением и/или проектом Firebase.
Убедитесь, что ключ API, указанный в файле конфигурации или объекте Firebase, совпадает с ключом API вашего приложения. Все ключи API можно посмотреть в консоли Google Cloud на панели API и сервисы > Учетные данные.
Если они не совпадают, получите новый файл или объект конфигурации Firebase и замените им тот, который находится в вашем приложении. Новый файл или объект конфигурации должен содержать действительный ключ API для вашего приложения и проекта Firebase.
Ошибка 400: Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.
Если вы пытаетесь отправить мультимодальный запрос с URL Cloud Storage for Firebase, может возникнуть следующая ошибка 400:
Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.
Эта ошибка возникает, если при включении API Agent Platform в проекте не были автоматически созданы необходимые агенты сервисов. Это известная проблема, которая возникает в некоторых проектах. Мы работаем над ее решением.
Вот как можно исправить проект и правильно настроить агентов сервиса, чтобы вы могли включать URL Cloud Storage for Firebase в мультимодальные запросы. Вы должны быть владельцем проекта. Выполнить эти действия нужно только один раз.
Получать доступ к gcloud CLI и выполнять аутентификацию в нем.
Проще всего это сделать в Cloud Shell. Подробные сведения можно найти в документации по Google Cloud.Если появится запрос, следуйте инструкциям в терминале, чтобы запустить gcloud CLI в проекте Firebase.
Вам понадобится идентификатор проекта Firebase. Его можно найти в верхней части страницы settings Project settings (Настройки проекта) в консоли Firebase.
Инициализируйте необходимых агентов сервисов в проекте, выполнив следующую команду:
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 ''
Подождите несколько минут, чтобы убедиться, что агенты сервиса подготовлены, а затем повторите отправку мультимодального запроса, включающего URL Cloud Storage for Firebase.
Если через несколько минут ошибка не исчезнет, обратитесь в службу поддержки 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
Если вы получили ошибку 403 - PERMISSION_DENIED с сообщением To access this model, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check, это значит, что в вашем запросе нет действительного токена App Check и вы пытаетесь получить доступ к модели, которая часто используется не по назначению.
Некоторые генеративные модели часто используются злоумышленниками.
Без App Check ваш проект уязвим для злоупотреблений этими моделями. Чтобы защитить разработчиков, Firebase блокирует доступ к этим моделям, если в запросах нет действительного токена App Check (для этого требуется принудительное применение App Check для Firebase AI Logic).
Если вы хотите получить доступ к модели, которая вернула ошибку, выполните следующие действия:
Настройте App Check для Firebase AI Logic. Для локальной разработки настройте App Check отладочный поставщик.
Если вы уже настроили App Check, убедитесь, что вы выполнили все шаги, описанные в инструкциях по ссылке.
Повторно отправьте запрос из приложения в Firebase AI Logic.
В этом запросе будет отправлен действительный токен App Check, и вы больше не будете получать ошибку 403.
Ошибка 403 не исчезла?
Если App Check применяется и вы отправили запрос, но по-прежнему получаете ошибку 403, проверьте, применяется ли защита от повторного воспроизведения для Firebase AI Logic (в том числе в режиме "Только мониторинг").
Когда защита от повторного воспроизведения включена, только одноразовые токены считаются подтвержденными для Firebase AI Logic. Это значит, что обычные токены сеанса не могут устранить ошибку 403. Чтобы устранить эту проблему, выполните одно из следующих действий:
Вариант 1. Если вы хотите использовать защиту от повторного воспроизведения, проверьте ее настройки.
Убедитесь, что вы выполнили все шаги по настройке защиты от повторного воспроизведения, в том числе включили одноразовые токены в базе кода приложения.
Отправить запрос повторно (Firebase AI Logic).
Вариант 2. Если вы не хотите использовать защиту от повторного воспроизведения или в вашем приложении не включены одноразовые токены, вы можете отключить защиту от повторного воспроизведения.
Отключите защиту от повторного воспроизведения в консоли Firebase. Для этого перейдите в раздел Security (Безопасность) > App Check (Проверка приложений) > APIs (API), разверните строку Firebase AI Logic, нажмите Set up (Настроить) и отключите защиту от повторного воспроизведения в диалоговом окне.
Отправить запрос повторно (Firebase AI Logic).
Прежде чем выпустить приложение для конечных пользователей, вам нужно настроить поставщика подтверждения рабочей версии (например, App Attest, Play Integrity или reCAPTCHA Enterprise), чтобы конечные пользователи могли получить доступ к ИИ-функции, когда App Check будет применяться принудительно.
Ошибка 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
Если вы получаете ошибку 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 был идентифицирован как неактивный и запросы из вашего приложения не имеют действительного токена App Check.
Неактивными считаются проекты, в которых включен Firebase AI Logic, но в последнее время не использовался Firebase AI Logic.
Без App Check ваш проект уязвим для злоупотребления Gemini API. Чтобы защитить ваш проект, Firebase отключил использование Firebase AI Logic, пока ваши запросы не будут включать действительный токен App Check (для этого требуется, чтобы App Check был принудительно включен для Firebase AI Logic).
Когда вы будете готовы снова использовать Firebase AI Logic, сделайте следующее:
Настройте App Check для Firebase AI Logic. Для локальной разработки настройте App Check отладочный поставщик.
Если вы уже настроили App Check, убедитесь, что вы выполнили все шаги, описанные в инструкциях по ссылке.
Повторно отправьте запрос из приложения в Firebase AI Logic.
В этом запросе будет отправлен действительный токен App Check, и вы больше не будете получать ошибку 403.
Ошибка 403 не исчезла?
Если App Check применяется и вы отправили запрос, но по-прежнему получаете ошибку 403, проверьте, применяется ли защита от повторного воспроизведения для Firebase AI Logic (в том числе в режиме "Только мониторинг").
Когда защита от повторного воспроизведения включена, только одноразовые токены считаются подтвержденными для Firebase AI Logic. Это значит, что обычные токены сеанса не могут устранить ошибку 403. Чтобы устранить эту проблему, выполните одно из следующих действий:
Вариант 1. Если вы хотите использовать защиту от повторного воспроизведения, проверьте ее настройки.
Убедитесь, что вы выполнили все шаги по настройке защиты от повторного воспроизведения, в том числе включили одноразовые токены в базе кода приложения.
Отправить запрос повторно (Firebase AI Logic).
Вариант 2. Если вы не хотите использовать защиту от повторного воспроизведения или в вашем приложении не включены одноразовые токены, вы можете отключить защиту от повторного воспроизведения.
Отключите защиту от повторного воспроизведения в консоли Firebase. Для этого перейдите в раздел Security (Безопасность) > App Check (Проверка приложений) > APIs (API), разверните строку Firebase AI Logic, нажмите Set up (Настроить) и отключите защиту от повторного воспроизведения в диалоговом окне.
Отправить запрос повторно (Firebase AI Logic).
Прежде чем выпустить приложение для конечных пользователей, вам нужно настроить поставщика подтверждения рабочей версии (например, App Attest, Play Integrity или reCAPTCHA Enterprise), чтобы конечные пользователи могли получить доступ к ИИ-функции, когда App Check будет применяться принудительно.
Ошибка 403: PERMISSION_DENIED: The caller does not have permission.
Если вы получаете ошибку 403 с сообщением PERMISSION_DENIED: The caller does not have permission., это обычно означает, что ключ API в файле или объекте конфигурации Firebase принадлежит другому проекту Firebase.
Убедитесь, что ключ API, указанный в файле конфигурации или объекте Firebase, совпадает с ключом API вашего приложения. Все ключи API можно посмотреть в консоли Google Cloud на панели API и сервисы > Учетные данные.
Если они не совпадают, получите новый файл или объект конфигурации Firebase и замените им тот, который находится в вашем приложении. Новый файл или объект конфигурации должен содержать действительный ключ API для вашего приложения и проекта Firebase.
Ошибка 403: Requests to this API firebasevertexai.googleapis.com ... are blocked.
Если вы получаете ошибку 403 с сообщением Requests to this API firebasevertexai.googleapis.com ... are blocked., это обычно означает, что ключ API в конфигурации Firebase в вашем приложении имеет ограничения, которые не позволяют ему вызывать нужный API.
Чтобы устранить эту проблему, обновите ограничения ключа API в консоли Google Cloud, добавив нужный API. Для Firebase AI Logic необходимо убедиться, что Firebase AI Logic API (firebasevertexai.googleapis.com) включен в список выбранных API, которые можно вызывать с помощью ключа API.
Для этого выполните следующие действия:
В консоли Google Cloud откройте панель APIs & Services (API и сервисы) > Credentials (Учетные данные).
Выберите ключ API, для использования которого настроено ваше приложение (например, "Ключ iOS" для приложения iOS).
На странице Edit API key (Изменить ключ API) найдите раздел API restrictions (Ограничения API).
Убедитесь, что выбран вариант Restrict key (Задать ограничения для ключа). Если нет, то ключ не ограничен и, скорее всего, не является причиной ошибки.
В раскрывающемся меню Selected APIs (Выбранные API) найдите и выберите Firebase AI Logic API, чтобы добавить его в список выбранных API, которые можно вызывать с помощью ключа API.
Нажмите Сохранить.
Изменения вступят в силу в течение пяти минут.
Ошибка 404: Firebase AI Logic genai config not found
Если вы получаете ошибку 404 с сообщением Firebase AI Logic genai config not found, обычно это означает, что параметр Firebase AI Logic настроен неправильно или отсутствует.
Вот наиболее вероятные причины этой ошибки:
Вы ещё не настроили проект Firebase для поставщика Gemini API.
Что нужно сделать:
В консоли Firebase выберите AI Services (Сервисы ИИ) > AI Logic (Логика ИИ). Нажмите Начать и выберите поставщика Gemini API. Включите API, и Firebase настроит ваш проект для этого поставщика. После этого повторите попытку.Если вы недавно настроили Firebase AI Logic в консоли Firebase, конфигурация 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 Hydrogen:
gemini-4-hydrogen - Последняя модель Gemini 4 Argon:
gemini-4-argon - Последняя модель Gemini 4 Carbon:
gemini-4-carbon - Последняя модель 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 Hydrogen:
Отключение (устаревшая модель)
Причина. Модель, к которой вы пытаетесь получить доступ, была отключена (например, модели Gemini 2.5 общего назначения в Agent Platform Gemini API (formerly Vertex AI), Gemini 2.0 или Imagen).
Решение. Ознакомьтесь с часто задаваемыми вопросами об устаревших и отключенных моделях и обновите код, чтобы использовать активную модель замены.
Недопустимое местоположение (только если используется поставщик 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 Live API 2.5 Доступны во многих странах, но не доступны в
global. (Обратите внимание, что модели Gemini 2.5 общего назначения для Agent Platform Gemini API (formerly Vertex AI) отключены.)
- При использовании синтаксиса инициализации 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. Этот уровень позволяет начать работу без указания способа оплаты, а значит вам не нужно переходить на тарифный план 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…
Подробную информацию вы найдете в Gemini Developer API документации по ценам и часто задаваемых вопросах об оплате.