На этой странице приведены инструкции по устранению неполадок, связанных с распространенными кодами ошибок в 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 AI Logic, ваш проект уязвим для злоупотреблений этими моделями. Чтобы защитить разработчиков, Firebase блокирует доступ к этим моделям, если в запросе нет действительного токена App Check (то есть для Firebase AI Logic применяется App Check).
Если вы хотите получить доступ к модели, которая вернула ошибку, выполните следующие действия:
Настройте App Check для Firebase AI Logic. Для локальной разработки настройте App Check отладочный поставщик.
Применение App Check критически важно для защиты моделей Gemini API и Gemini от злоупотреблений. Чтобы устранить эту ошибку, необходимо обеспечить соблюдение правил.
Повторно отправьте запрос из приложения в Firebase AI Logic.
Вместе с этим запросом будет отправлен действительный токен App Check, и вы больше не будете получать ошибку
403 - PERMISSION_DENIED.Прежде чем выпустить приложение для конечных пользователей, вам нужно настроить поставщика аттестации рабочей версии (например, 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, но он не использовался в последнее времяFirebase AI Logic.
Поскольку вы не включили App Check для Firebase AI Logic, ваш проект уязвим к злоупотреблению Gemini API. Чтобы защитить ваш проект, Firebase деактивирует использование Firebase AI Logic, пока вы не включите App Check для Firebase AI Logic.
Когда вы будете готовы снова использовать Firebase AI Logic, сделайте следующее:
Настройте App Check для Firebase AI Logic. Для локальной разработки настройте 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 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 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. Этот уровень позволяет начать работу без указания способа оплаты, то есть вам не нужно переходить на тарифный план 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 документации по ценам и часто задаваемых вопросах об оплате.