Ошибки API

На этой странице приведены коды ошибок, возвращаемые GenerateContent API, описан формат ответа об ошибке gRPC и даны инструкции по устранению неполадок.

Коды ошибок HTTP

В таблице ниже перечислены распространенные коды ошибок бэкенда, объяснения их причин и рекомендуемые решения.

HTTP-код Статус Описание Пример Решение
400 INVALID_ARGUMENT Тело запроса имеет неверный формат. В запросе есть опечатка или отсутствует обязательное поле. Формат запроса, примеры и поддерживаемые версии можно найти в документации по API. Использование функций из более новой версии API со старой конечной точкой может привести к ошибкам.
400 FAILED_PRECONDITION Бесплатный план Gemini API недоступен в вашей стране. Включите оплату для проекта в Google AI Studio. Вы отправляете запрос из региона, где бесплатный план не поддерживается, и вы не включили оплату в своем проекте в Google AI Studio. Чтобы использовать Gemini API, вам нужно будет оформить платный тариф в Google AI Studio.
402 RESOURCE_EXHAUSTED Ваш баланс предоплаты исчерпан. В вашем платежном аккаунте закончились средства предоплаты, поэтому все ключи API, связанные с этим платежным аккаунтом, перестали работать. Добавьте средства в платежный аккаунт или включите автоматическое пополнение. Не повторяйте этот запрос: он не будет выполнен, пока не будут добавлены средства.
403 PERMISSION_DENIED У вашего ключа API нет необходимых разрешений или доступ к API вашего проекта ограничен. Вы используете неправильный или утекший ключ API, ваш проект не допущен для бесплатного плана, у вашего платежного аккаунта есть текущая задолженность или вы пытаетесь использовать настроенную модель, не пройдя надлежащую аутентификацию. Убедитесь, что ключ API действителен и активен, проверьте статус платежей и уровень проекта в Google AI Studio или ознакомьтесь с разделом Устранение неполадок: проект ограничен или недоступен.
404 NOT_FOUND Запрошенный ресурс не найден. Не удалось найти файл изображения, аудио или видео, указанный в запросе. Проверьте, все ли параметры в запросе допустимы для вашей версии API.
429 RESOURCE_EXHAUSTED Вы превысили одно из ограничений API (на количество запросов в минуту, токенов в минуту, запросов в день, расходы и т. д.). Вы отправляете слишком много запросов, используете слишком много токенов или превышаете лимиты на расходы, установленные для истории платежей и уровня вашего аккаунта. Убедитесь, что вы не превысили ограничения частоты запросов. Подождите и повторите попытку через некоторое время. Уменьшите частоту или размер запросов. При необходимости запросите увеличение ограничения частоты запросов.
499 ОТМЕНЕН Операция отменена, как правило, отправителем вызова. Клиент закрыл подключение до того, как API завершил ответ. Проверьте, не закрывает ли клиент или сетевая инфраструктура соединение преждевременно (например, из-за клиентского тайм-аута).
500 ДЛЯ ВНУТРЕННЕГО ИСПОЛЬЗОВАНИЯ На стороне Google произошла непредвиденная ошибка. Контекст слишком длинный. Проверьте, нет ли текущих инцидентов, на странице статуса Gemini API. Уменьшите контекст входных данных или временно переключитесь на другую модель (например, с Gemini 2.5 Pro на Gemini 2.5 Flash) и посмотрите, работает ли она. или повторите попытку позже. Если проблема не исчезнет, сообщите о ней, нажав кнопку Отправить отзыв в Google AI Studio.
503 UNAVAILABLE Возможно, сервис временно перегружен или не работает. Сервис временно перегружен. Проверьте, нет ли текущих инцидентов, на странице статуса Gemini API. Временно переключитесь на другую модель (например, с Gemini 2.5 Pro на Gemini 2.5 Flash) и проверьте, работает ли она. или повторите попытку позже. Если проблема не исчезнет, сообщите о ней, нажав кнопку Отправить отзыв в Google AI Studio.
504 DEADLINE_EXCEEDED Сервис не может завершить обработку в установленный срок. Ваш запрос (или контекст) слишком большой, чтобы его можно было обработать вовремя. Чтобы избежать этой ошибки, задайте в запросе клиента более длительное время ожидания.

Формат ответа об ошибке

Если запрос GenerateContent не выполняется, API устанавливает код статуса HTTP (например, 400 Bad Request, 403 Forbidden или 429 Too Many Requests) и возвращает тело ответа JSON, содержащее сведения о статусе gRPC:

{
  "error": {
    "code": 400,
    "message": "API key not valid. Please pass a valid API key.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "API_KEY_INVALID",
        "domain": "googleapis.com",
        "metadata": {
          "service": "generativelanguage.googleapis.com"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
        "locale": "en-US",
        "message": "API key not valid. Please pass a valid API key."
      }
    ]
  }
}
Поле Тип Описание
code Целое число Код статуса HTTP.
message string Человекочитаемое описание ошибки.
status string Код статуса gRPC в SCREAMING_CASE.
details Массив Дополнительный контекст ошибки, например ErrorInfo или LocalizedMessage.

Дальнейшие действия