Gemini API key: ошибка 403 Permission Denied — диагностика по месту отказа (2026)

Ответ Gemini API 403 PERMISSION_DENIED не означает «повторите запрос позже». Сначала выясните, какое действие было отклонено: создание key в Google AI Studio, вызов Gemini Developer API, генерация внутри AI Studio или обращение к модели и клиентскому маршруту с другим способом аутентификации. До изменений сохраните HTTP status, точный текст ошибки, hostname endpoint, выбранный project, model, время и request ID. Полное значение key сохранять или отправлять нельзя.

Сначала проверьте только наличие переменных, не печатая секрет:

bash
printf 'GOOGLE_API_KEY=%s\n' "${GOOGLE_API_KEY:+set}"
printf 'GEMINI_API_KEY=%s\n' "${GEMINI_API_KEY:+set}"

Если заданы обе, текущая документация клиентских библиотек Google отдаёт приоритет GOOGLE_API_KEY. После подтверждения endpoint и project выполните две одинаковые контрольные операции: список моделей, затем одну минимальную генерацию. Отказ на списке оставляет вас в ветке key/project/restriction/endpoint. Успешный список и отказ генерации переводят расследование к model/action/auth. Если обе операции успешны, сравнивайте local и deployment configuration.

Остановите создание новых keys и projects, когда чистые canary повторяют отказ или AI Studio показывает account-level blocked/suspicious на нескольких корректных объектах. Для администратора или поддержки подготовьте sanitized error, project ID, короткий fingerprint key, endpoint, model, timestamp, request ID и результаты двух проверок.

Один текст 403 скрывает разные владельцы отказа

API key — credential, связанный с Google Cloud project. Он не является IAM policy, billing account, quota bucket, выбранной model, endpoint или вошедшим аккаунтом AI Studio. Поэтому «ключ существует» и даже «ключ работал вчера» не доказывают право выполнить сегодняшнее действие.

Текущий troubleshooting guide Gemini API описывает 403 PERMISSION_DENIED как отсутствие требуемых permissions у key. Среди примеров — неправильный key и tuned model без требуемой аутентификации. Там же Google не рекомендует повторять client errors 400 и 403. Повтор меняет только время; здесь обычно нужно изменить credential ownership, restriction или authentication contract.

Русскоязычная выдача в основном состоит из отдельных incidents: новые projects, caching, Gemini CLI, конкретные preview models, личные аккаунты и AI Studio. Такие случаи полезны как симптомы, но не дают универсального диагноза. Рабочий вопрос звучит не «какой из десяти советов попробовать», а «какое действие отклонено и какая система его контролирует».

Сохраните ошибку до ротации и изменения IAM

Первый failed request часто является самым чистым доказательством. До ротации, смены project, редактирования restrictions или redeploy запишите:

• UTC timestamp и локальную timezone;
• HTTP status, status name и sanitized response body;
• endpoint hostname, API version и method;
• model или resource path;
• project ID;
• SDK/client version;
• request ID, trace ID или correlation ID, если они вернулись;
• место сбоя: AI Studio, local, CI или production;
• отличаются ли результаты models.list и минимального generateContent.

Не прикладывайте full key, screenshot с секретом, полный environment dump, cookies, OAuth tokens, service-account JSON или production payload с приватными данными.

Для сравнения local, CI и production можно получить короткий односторонний fingerprint:

bash
if [ -n "${GOOGLE_API_KEY:-}" ]; then
  ACTIVE_KEY="$GOOGLE_API_KEY"
  KEY_SOURCE="GOOGLE_API_KEY"
elif [ -n "${GEMINI_API_KEY:-}" ]; then
  ACTIVE_KEY="$GEMINI_API_KEY"
  KEY_SOURCE="GEMINI_API_KEY"
else
  echo "Gemini API key variable is not set"
  exit 1
fi

printf 'source=%s length=%s sha256=' "$KEY_SOURCE" "${#ACTIVE_KEY}"
printf '%s' "$ACTIVE_KEY" | shasum -a 256 | cut -c1-12

Первые 12 символов hash — не key. Они помогают доказать, одинаковый ли secret использовали среды. Но даже fingerprint лучше оставлять внутри incident или защищённого support channel.

Две canary-проверки отделяют credential от действия модели

Смысл проверки — удерживать credential, project и endpoint неизменными. Исправляйте один подтверждённый mismatch и запускайте те же запросы снова.

Шаг 1. Получить список моделей

Для Gemini Developer API используется generativelanguage.googleapis.com. Здесь key передаётся через header descriptor, а body сохраняется локально:

bash
LIST_HTTP=$(
  curl --silent --show-error \
    --output /tmp/gemini-models.json \
    --write-out '%{http_code}' \
    --header @<(printf 'x-goog-api-key: %s\n' "$ACTIVE_KEY") \
    'https://generativelanguage.googleapis.com/v1beta/models'
)
printf 'models.list HTTP %s\n' "$LIST_HTTP"
jq '{error, model_count: (.models | length?)}' /tmp/gemini-models.json

403 здесь указывает на active key, project, key state, restriction или endpoint. Код 200 со списком подтверждает baseline access, но не разрешение на все actions. Ответ 404 или странный JSON сначала требует проверки hostname, API version, proxy/base URL и request construction. Код 429 уже относится к quota/rate limit, а не к этой 403-ветке.

Шаг 2. Минимальная генерация

Возьмите из list response актуальный model path, у которого явно указана поддержка generateContent. Не копируйте старый model ID. Перед тестом проверьте текущие pricing и eligibility: canary остаётся реальным API call.

bash
MODEL_PATH='models/<current-model-from-list-with-generateContent>'

GEN_HTTP=$(
  curl --silent --show-error \
    --output /tmp/gemini-generate.json \
    --write-out '%{http_code}' \
    --request POST \
    --header @<(printf 'x-goog-api-key: %s\n' "$ACTIVE_KEY") \
    --header 'Content-Type: application/json' \
    --data '{"contents":[{"parts":[{"text":"Reply with OK."}]}]}' \
    "https://generativelanguage.googleapis.com/v1beta/${MODEL_PATH}:generateContent"
)
printf 'generateContent HTTP %s\n' "$GEN_HTTP"
jq '{error, candidates: (.candidates | length?)}' /tmp/gemini-generate.json

После фиксации sanitized results удалите временные файлы:

bash
rm -f /tmp/gemini-models.json /tmp/gemini-generate.json
unset ACTIVE_KEY

Если AI Studio не разрешает создать key в project

Этот отказ возникает до появления usable key. Model names, generateContent и retry logic не имеют к нему отношения.

Текущий Google guide по Gemini API keys говорит, что каждый key принадлежит Google Cloud project. AI Studio не показывает автоматически все existing projects; сначала импортируйте нужный project в Projects view.

Для текущего authorization-key flow документация называет два permissions:

• resourcemanager.projects.get — проверка project;
• iam.serviceAccountApiKeyBindings.create — связывание service account с key.

Администратор должен предоставить role, содержащую нужные permissions. Project Editor указан Google как пример, но это широкая роль. В управляемой организации безопаснее запросить минимальный одобренный predefined/custom role, а не Owner.

Google Cloud IAM reference подтверждает apikeys.keys.create для API Keys Admin. Это не отменяет новый binding step. Permission нужно сопоставлять с отклонённой операцией.

Новый project вне организации допустим только как законная ownership boundary, если у вас нет административного доступа. Он не должен обходить organization policy, review, quota, billing или account enforcement.

Что изменилось, если старый key внезапно перестал работать

Сначала докажите, что приложение читает тот же key

Google clients могут автоматически брать GEMINI_API_KEY и GOOGLE_API_KEY; вторая переменная имеет приоритет. Частые причины: старый GOOGLE_API_KEY перекрывает новый, local и deployment используют разные secret stores, CI variable переопределяет project secret, процесс не перезапущен после rotation, framework читает отдельную provider config. Сравните fingerprints и только затем уберите устаревший дубль.

Нерестриктированный standard key больше не соответствует контракту

Текущий key guide сообщает: с 19 июня 2026 года Gemini API начал отклонять запросы с unrestricted standard keys. Standard keys с явными restrictions могут продолжать работать, а новые keys AI Studio создаются как authorization keys.

Не добавляйте случайную restriction. Проверьте allowed APIs, соответствие origin/server IP, необходимость разделить multi-API credential и целесообразность нового authorization key.

Долгое бездействие привело к состоянию Blocked

По той же документации с 7 мая 2026 года unrestricted keys, не используемые длительное время, могут блокироваться и получать tag Blocked в AI Studio. Единого публичного числа дней Google не даёт. Не придумывайте срок.

Используйте новый authorization key или существующий restricted key. Сначала проверьте замену в low-risk environment, потом отключайте старый credential.

Key распознан как leaked

Известно скомпрометированные keys Google может proactive block. Создайте replacement, обновите local/deployed secrets, выполните те же canaries, проверьте usage и billing на чужие вызовы, отключите старый key после успешной проверки и удалите источник утечки из Git history, client bundle, logs, screenshots или docs.

Restrictions: разрешённый API и источник запроса — разные вещи

API restriction определяет, к каким Google APIs может обращаться key. Для Developer API разрешённый набор должен соответствовать Generative Language API/Gemini route в текущей консоли. Не используйте один production key для множества несвязанных APIs, если отдельные credentials дают яснее ownership.

Application restriction связывает использование с server IP, HTTP referrer, Android app или iOS app. Local может работать, а production — нет после смены egress IP. Обратный случай возникает, когда server-only key отправляют из browser. Записывайте фактический request origin.

Key в production browser/mobile code — отдельный security incident. Backend proxy не отменяет rotation уже раскрытого секрета. Нужно заменить key, проверить service, отключить старый и найти источник публикации.

Developer API и Vertex AI требуют разных auth contracts

Canaries выше относятся к generativelanguage.googleapis.com, то есть Gemini Developer API. Vertex AI использует project/location resources, другой endpoint и identity. Framework может переключить route через base URL, provider flag или environment variable.

Если ошибка содержит aiplatform.googleapis.com, location, publisher model, OAuth, Application Default Credentials или service account, остановите инструкции для Developer API key. Сначала определите Vertex identity и IAM. И наоборот, не добавляйте Vertex roles к прямому Developer API request лишь потому, что обе поверхности называются Gemini.

Tuned model может быть единственным закрытым действием

403 example Google отдельно упоминает tuned model без нужной authentication. Узнайте owner модели, проверьте authorization вызывающей identity, resource path, project и обязательный auth method. Сравните base-model canary с tuned request.

Если base model отвечает, а tuned model нет, новый общий API key редко является минимальным исправлением. Проблема находится в ACL или authentication защищённого ресурса.

Не лечите соседние status codes как 403

При фактическом 429 используйте guide по Gemini API free tier и live quota, а не создавайте keys. Если после восстановления permission обнаружился usage-tier вопрос, смотрите Gemini API Tier 3 guide. Credential и quota entitlement — разные контракты.

Проверка исправления и безопасный rollback

Recovery закончено не при создании key, а когда те же тесты проходят в целевой среде:

1. Запишите project, endpoint, API version, model path и credential owner.
2. Запустите models.list после исправления.
3. Выполните ту же минимальную генерацию.
4. Повторите тест из deployment.
5. Убедитесь, что monitoring и usage относятся к ожидаемому project.
6. Обновите secret manager и restart/redeploy consuming process.
7. Уберите duplicate variables.
8. Отключите старый key только после успешной замены.
9. Удалите temporary responses и unset переменные.
10. Запишите root cause и единственное изменение, которое сработало.

Rollback означает возврат к последней известной рабочей restriction или deployment revision. Leaked key включать обратно нельзя.

Когда нужен администратор или поддержка Google

Project/organization admin нужен, если project нельзя импортировать или просмотреть, не хватает current create-key permissions, organization policy запрещает key, restriction управляется централизованно либо project/service account/tuned model принадлежит другой команде.

К Google следует эскалировать, когда sanitized 403 сохраняется с current key, correct project, endpoint и restrictions; AI Studio сообщает blocked/suspicious на чистых объектах; отказ следует за account; response называет enforcement, которым вы не управляете; или есть minimal reproduction и request ID без оставшегося self-service owner.

Пакет содержит project ID, source variable и short fingerprint, endpoint/version/method/model/time, sanitized body, request ID, результаты canaries, environment/client version и change history. Полный key не нужен ни администратору, ни обычной форме поддержки.

Профилактика

• Один понятный credential owner на environment.
• Не допускайте скрытой конкуренции GOOGLE_API_KEY и GEMINI_API_KEY.
• Используйте текущий AI Studio authorization-key route, когда он подходит.
• Ограничивайте key целевым API и реальным origin.
• Production calls выполняйте через backend и secret manager.
• Разделяйте credentials для несвязанных APIs и environments.
• Следите за usage/billing anomalies.
• Rotate при exposure, а не при любом error.
• Храните model-list и minimal-generation canary в runbook.
• До launch зафиксируйте owners project, endpoint, model и restrictions.

Часто задаваемые вопросы

Почему Gemini API key получает Permission Denied?

Key может быть неправильным, перекрытым другой env variable, принадлежать другому project, иметь Blocked/leaked state или restriction, не совпадающую с API/origin. Также baseline access может работать без права на конкретную model/action. Начните с места отказа и двух canaries.

Нужно ли повторять 403?

Нет. Google относит 403 к client-side permission/authentication errors и не рекомендует retry 400/403. Измените только доказанного владельца и повторите ту же проверку.

Почему AI Studio работает, а API call нет?

Поверхности могут использовать разные accounts, projects, credentials, endpoints, models и restrictions. Сравните выбранный AI Studio project, owning project key и fingerprint deployed secret.

Почему список моделей есть, а генерация запрещена?

Model list доказывает baseline visibility, но не все actions. Проверьте поддержку generateContent, tuned-model ownership, resource path, endpoint, project policy и точный 403 body.

Какая переменная важнее: GOOGLE_API_KEY или GEMINI_API_KEY?

При одновременной установке текущая документация Google даёт приоритет GOOGLE_API_KEY. Сначала установите фактически читаемый source, затем удалите obsolete duplicate.

Заблокировал ли Google старые unrestricted keys?

Guide сообщает о rejection unrestricted standard keys с 19 июня 2026 года и возможной блокировке долго dormant unrestricted keys с 7 мая 2026 года. Проверяйте status и restrictions своего key, а не делайте вывод обо всех старых keys.

Нужен ли API Keys Admin для AI Studio?

Не всегда как полный ответ. Он покрывает standard operations вроде apikeys.keys.create; current authorization-key flow отдельно называет resourcemanager.projects.get и iam.serviceAccountApiKeyBindings.create.

Исправит ли billing ошибку 403?

Не универсально. Google относит один случай unsupported free-tier region без billing к 400 FAILED_PRECONDITION, а 403 — к permission/authentication. Решение выбирают по точному status и message.

Поможет ли новый project?

Законно принадлежащий вам project может решить ownership boundary, но не должен обходить organization policy, quota, review или account enforcement. Если clean projects повторяют account-level denial, остановитесь и эскалируйте с evidence.

Правило восстановления

Считайте Gemini permission denied проблемой ownership, а не времени. Докажите denied action, active key, project, endpoint, key state, restrictions и model auth. Вносите одно ограниченное изменение, повторяйте те же canaries, проверяйте deployment и передавайте только sanitized evidence.