Ошибки API

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

коды ошибок HTTP

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

HTTP-код Статус Описание Пример Решение
400 НЕВЕРНЫЙ АРГУМЕНТ Тело запроса имеет некорректный формат. В вашем запросе допущена опечатка или отсутствует обязательное поле. Для получения информации о формате запроса, примерах и поддерживаемых версиях ознакомьтесь со справочником API . Использование функций более новой версии API со старой конечной точкой может привести к ошибкам.
400 НЕУДАЧНОЕ ПРЕДУСЛОВИЕ Бесплатный тариф Gemini API недоступен в вашей стране. Пожалуйста, включите оплату для вашего проекта в Google AI Studio. Вы отправляете запрос из региона, где бесплатный тариф не поддерживается, и у вас не включена оплата за использование сервиса в Google AI Studio. Для использования API Gemini вам потребуется оформить платный тарифный план в Google AI Studio .
403 ДОСТУП ЗАПРЕЩЕН Ваш API-ключ не обладает необходимыми правами доступа. Вы используете неправильный ключ API; вы пытаетесь использовать оптимизированную модель без надлежащей аутентификации . Убедитесь, что ваш API-ключ настроен и имеет необходимые права доступа. И обязательно пройдите надлежащую аутентификацию для использования оптимизированных моделей.
404 НЕ НАЙДЕНО Запрошенный ресурс не найден. Изображение, аудио- или видеофайл, указанные в вашем запросе, не найдены. Проверьте, все ли параметры в вашем запросе соответствуют вашей версии API.
429 ИСТЕЧЕНИЕ РЕСУРСОВ Вы превысили один из лимитов скорости API (RPM, TPM, RPD, сумма расходов и т. д.). Вы отправляете слишком много запросов, используете слишком много токенов или превышаете лимиты расходов, установленные для вашей учетной записи и уровня тарифа. Убедитесь, что вы находитесь в пределах лимитов скорости, установленных моделью. Подождите и повторите попытку через короткое время. Уменьшите скорость или размер ваших запросов. При необходимости запросите увеличение лимита скорости .
499 ОТМЕНЕНО Операция была отменена, как правило, самим звонившим. Клиент разорвал соединение до того, как API смог завершить обработку запроса. Проверьте, не закрывает ли ваше клиентское приложение или сетевая инфраструктура соединение преждевременно (например, из-за таймаута на стороне клиента).
500 ВНУТРЕННИЙ На стороне Google произошла непредвиденная ошибка. Ваш контекст ввода слишком длинный. Проверьте страницу состояния API Gemini на наличие текущих инцидентов. Уменьшите контекст ввода или временно переключитесь на другую модель (например, с Gemini 2.5 Pro на Gemini 2.5 Flash) и посмотрите, заработает ли это. Или подождите немного и повторите запрос. Если проблема сохраняется после повторной попытки, пожалуйста, сообщите о ней, используя кнопку «Отправить отзыв» в Google AI Studio.
503 НЕДОСТУПНО Сервис может быть временно перегружен или недоступен. В настоящее время сервис временно недоступен. Проверьте страницу состояния API Gemini на наличие текущих инцидентов. Временно переключитесь на другую модель (например, с Gemini 2.5 Pro на Gemini 2.5 Flash) и посмотрите, заработает ли она. Или подождите немного и повторите запрос. Если проблема сохраняется после повторной попытки, пожалуйста, сообщите о ней, используя кнопку «Отправить отзыв» в Google AI Studio.
504 СРОК ПРЕВЫШЕН Сервис не может завершить обработку в установленный срок. Ваш запрос (или контекст) слишком обширен, чтобы его можно было обработать за отведенное время. Чтобы избежать этой ошибки, установите более высокий «тайм-аут» в запросе клиента.

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

Когда запрос 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 нить Удобочитаемое описание ошибки.
status нить Код состояния gRPC в SCREAMING_CASE .
details множество Дополнительный контекст ошибки, например, ErrorInfo или LocalizedMessage .

Что дальше?