Ошибки API Gemini 4 Carbon, Neon и Hydrogen: как найти причину и исправить

Диагностика ошибок API Gemini 4 Carbon, Neon и Hydrogen: неверные ID моделей, ограничения бесплатного уровня, 429, уровни рассуждений, пустые ответы, вызовы инструментов и блокировки безопасности.

Линейный рисунок открытого электрощита с двумя рядами автоматов; один из них, оранжевый, сработал.

Большинство ошибок Gemini 4 API относится к одной из пяти групп: неверный ID модели или маршрут; уровень проекта (Carbon и Neon доступны только на платном уровне); квота (429); неподдерживаемые параметры (minimal или xhigh на Carbon); и ответы, которые формально успешны, но не содержат ответа, потому что рассуждения израсходовали max_output_tokens. Определите группу по HTTP-статусу, полю code ошибки и структуре ответа. Новый API-ключ помогает только в одном узком случае: если ключ утёк или заблокирован.

Это руководство охватывает Gemini 4 Carbon, Neon и Hydrogen. Для Argon есть отдельный материал, разбор ошибок Gemini 4 Argon API, а шаблон описания инцидента и синтетические тесты оттуда здесь не повторяются. Сведения о Google ниже взяты из документации Gemini API и проверены 19 ноября 2026 года (ссылки на документацию Google ведут на англоязычные страницы). Результаты по Ofox получены из 21 реального запроса, которые мы в тот же день отправили через Ofox к google/gemini-4-hydrogen и google/gemini-4-argon, по одному запуску на случай (общая стоимость, по оценке, меньше 0,05 доллара). Carbon и Neon на Ofox недоступны (каталог проверен 19 ноября 2026 года), поэтому все примеры для Carbon и Neon используют нативный API Google.

Статью публикует Ofox. Если результат через шлюз расходится с документацией Google, приводятся оба варианта, а расхождение не выдаётся за правило для собственного эндпоинта Google.

Сначала определите симптом

Возьмите первую подходящую строку. Каждая строка ведёт к разделу с исправлением и способом проверки.

Что вы видитеНаиболее вероятная причинаЧто проверить первымРаздел
404 model_not_foundОпечатка, выдуманный суффикс или модель, которую ваш маршрут не обслуживаетСкопируйте ID из актуального списка моделей провайдераID модели
403 PERMISSION_DENIED с упоминанием верификации, бесплатного уровня или оплатыУровень проекта или состояние биллингаСтатус проекта в AI Studio, а не ключПлатный уровень
402 payment_requiredЗакончились предоплаченные кредитыБаланс; не повторяйте запросПлатный уровень
429 с rate_limit_exceeded / too_many_requestsВсплеск запросов в пределах минутыПараллельность и скорость расхода токенов429
429 с quota_exceededИсчерпана дневная квотаДождитесь сброса; повторы не помогут429
400 с упоминанием thinking_levelУровень недопустим для этой моделиТаблица уровней по моделямУровни рассуждений
400 после перехода с Gemini 3.xСтарые настройки сэмплирования, кеширования или промптов для инструментовЧек-лист миграцииМиграция
HTTP 200, пустой текст, MAX_TOKENS / length / incompleteРассуждения израсходовали бюджет выводаmax_output_tokens и thinking_levelБюджет вывода
Статус requires_continuationОдин шаг в обычном (не фоновом) режиме упёрся в свой лимитВерсия SDK или цикл продолженияБюджет вывода
Фоновая задача в статусе failed или завислаСбой на стороне сервера, лимит в 24 часа или store=falseСтатус interaction и список errorsФоновые задачи
missing_thought_signature, malformed_function_callИстория вызовов инструментов изменена или инструменты не объявленыКак история отправляется повторноВызовы инструментов
400 с кодом safety, prohibited_contentФильтр контентаПромпт и ваши настройки безопасностиБезопасность

Сначала смотрите на структуру ошибки, потом на сообщение

Google и шлюз вроде Ofox оформляют ошибки по-разному. Прежде чем действовать по тексту, проверьте, кто именно ответил.

Interactions API от Google возвращает объект error с машиночитаемым code и полем message, как описано в справочнике ошибок API:

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'. ..."
  }
}

При потоковой передаче тот же объект приходит как SSE-событие с "event_type": "error". Поток может начаться с HTTP 200 и всё равно завершиться ошибкой позже, поэтому код чтения потока должен обрабатывать события error. Устаревший generateContent API использует прежний стиль Google RPC со статусами вроде INVALID_ARGUMENT и RESOURCE_EXHAUSTED, поэтому на страницах Google по устранению неполадок встречаются оба варианта именования.

Шлюз Ofox в наших тестах возвращал ошибки двух видов. Если ID модели не было в каталоге шлюза, шлюз отвечал собственным телом ошибки (ID запроса сокращён). Формат сообщения совпадает со строкой про опечатку в ID модели в руководстве Ofox по Gemini:

{"error": {"message": "Model 'google/gemini-4-carbon' not found",
           "type": "model_not_found", "code": 404, "request_id": "e0925435-..."}}

Когда запрос доходил до Google (по руководству Ofox по Gemini, Ofox обслуживает Gemini через Vertex AI) и отклонялся там, текст вышестоящего сервиса возвращался внутри обёртки шлюза:

{"error": {"code": null,
  "message": "Invalid value at 'generation_config.thinking_config.thinking_level' (type.googleapis.com/google.cloud.aiplatform.v1.GenerationConfig.ThinkingConfig.ThinkingLevel),",
  "param": null, "request_id": "1439e1a1-...", "type": "INVALID_ARGUMENT"}}

Имя типа google.cloud.aiplatform в сообщении означает, что значение отклонил вышестоящий сервис модели. Сообщение Model '<id>' not found означает, что шлюз не распознал ID модели.

Руководство Ofox по обработке ошибок описывает коды статусов и указывает, какие из них можно повторять. В примере тела ошибки там указаны "code": "invalid_api_key" и "type": "authentication_error", а в таблице для 404 указан type not_found_error. Тела, которые мы получили 19 ноября 2026 года, выглядели иначе: у 401 были "code": 401 и "type": "invalid_api_key", у 404 — "code": 404 и "type": "model_not_found". Если ваш обработчик ветвится по этим полям, проверяйте и code, и type, и протестируйте его на ошибке, полученной на вашем собственном маршруте.

404 model not found: неверный ID или маршрут

Симптом. Google: 404 с кодом model_not_found. Ofox: 404 с type model_not_found и сообщением Model '<id>' not found.

Причина. Четыре ID моделей Gemini 4 в API Google — ровно gemini-4-carbon, gemini-4-neon, gemini-4-hydrogen и gemini-4-argon (страница моделей). Ни у одного нет суффикса -preview или -latest. Другая частая причина — маршрут, который вообще не обслуживает эту модель.

Наши запросы через Ofox 19 ноября 2026 года (по одному запуску):

Отправленная строка моделиЭндпоинтРезультат
google/gemini-4-hydrogen-preview/v1/chat/completions404 model_not_found
google/gemini-4-hydrogen-preview/gemini/v1beta/models/...:generateContent404 model_not_found
google/gemini-4-carbon/v1/chat/completions404 model_not_found
google/gemini-4-neon/v1/chat/completions404 model_not_found
gemini-4-hydrogen (без префикса google/)/v1/chat/completions200, поле model в ответе — google/gemini-4-hydrogen

Исправление. В Google используйте ID без префикса. В Ofox используйте google/gemini-4-hydrogen или google/gemini-4-argon. Вариант без префикса в нашем тесте тоже распознавался, и в руководстве Ofox по Gemini сказано, что префикс необязателен. Для Carbon или Neon используйте проект Google на платном уровне. Изменение написания не заставит появиться модель, которой нет в каталоге шлюза.

Проверка. Запросите список моделей через тот же эндпоинт и с тем же ключом, что использует ваше приложение: GET https://generativelanguage.googleapis.com/v1beta/models в Google или GET https://api.ofox.io/v1/models в Ofox. Google предупреждает, что models.list проверяет только существование ключа. Ответ 200 от эндпоинта списка не доказывает, что для проекта включён инференс, поэтому подтвердите это одним небольшим запросом на генерацию.

Carbon и Neon не работают в проекте на бесплатном уровне

Симптом. Запрос, который работает с Hydrogen, падает, когда вы меняете модель на Carbon или Neon. Типичные признаки: 403 PERMISSION_DENIED, статус проекта в AI Studio Free tier unavailable или Payment needed, либо ошибка квоты в проекте, для которого никогда не включали оплату.

Причина. В руководстве по Carbon сказано, что Carbon “is not available on the Free tier” (недоступен на бесплатном уровне). В руководстве по Neon — что Neon “available on the paid tier only” (доступен только на платном уровне). Hydrogen — единственная модель Gemini 4 с бесплатным уровнем (цены). Google не публикует отдельную строку ошибки для случая, когда проект на бесплатном уровне вызывает Carbon или Neon, поэтому не сопоставляйте точный текст. Ориентируйтесь на статус, а затем проверяйте проект.

В руководстве Google по устранению неполадок перечислены варианты 403 на уровне проекта:

СигналЗначениеИсправление
403 с FREE_TIER_VERIFICATION_REQUIRED, статус Verification neededПроект на бесплатном уровне должен пройти верификациюПройдите верификацию с мобильного устройства или настройте оплату
Статус Free tier unavailableПроект не может использовать бесплатный уровеньПривяжите активный аккаунт Cloud Billing
Статус Payment needed или 403 с упоминанием задолженностиУ платёжного аккаунта есть долгПогасите задолженность; доступ восстановится автоматически
403 о том, что ключ отмечен как утёкшийGoogle заблокировал ключСоздайте новый ключ и не храните его в клиентском коде
402 payment_requiredЗакончились предоплаченные кредитыПополните кредиты или включите автопополнение; не повторяйте запрос

На двух деталях часто спотыкаются. Право доступа проверяется для каждого проекта Google Cloud, поэтому другой ключ из того же проекта даст тот же результат. Переход на платный уровень также не открывает квоту бесплатного уровня: платное использование тарифицируется. Если бесплатный уровень возвращает 429 с лимитом 0, разбор ошибки с нулевым лимитом на бесплатном уровне Gemini (на английском) показывает, как читать метрику квоты. Он написан про модели изображений, но проверка проекта та же. Что входит в бесплатный уровень Hydrogen, описано в руководстве по бесплатному уровню Gemini 4 API.

Проверка. В AI Studio откройте проект, которому принадлежит ключ, и подтвердите уровень. Затем отправьте один короткий запрос к Carbon или Neon. Цены на Carbon и Argon удваиваются 1 декабря 2026 года (руководство по Carbon); цифры приведены в разборе декабрьского изменения цен.

429: отличите всплеск от исчерпанной квоты

Симптом. HTTP 429. В Interactions API код — rate_limit_exceeded, too_many_requests или quota_exceeded. В generateContent — RESOURCE_EXHAUSTED.

Причина. На странице лимитов Google зафиксированы три факта:

  • Лимиты действуют на проект, а не на API-ключ.
  • Дневные квоты запросов сбрасываются в полночь по тихоокеанскому времени.
  • У платных проектов есть ещё лимит по расходам в скользящем 10-минутном окне: 10 долларов на Tier 1 и 200 долларов на Tier 2 и Tier 3. При его превышении возвращается 429 RESOURCE_EXHAUSTED, даже если частота запросов низкая.

На Gemini 4 лимит по расходам легко упустить из виду. Neon и Hydrogen по умолчанию используют уровень рассуждений high, а токены рассуждений оплачиваются как выходные токены. Небольшое число длинных запросов с интенсивными рассуждениями может упереться в лимит расходов Tier 1, не нарушив ни одного лимита RPM.

Исправление. Выбирайте действие по коду:

КодЧто делатьЧего не делать
rate_limit_exceeded, too_many_requestsЭкспоненциальная задержка со случайным разбросом; снизить параллельностьСразу повторять запросы параллельно
quota_exceededПриостановить задачу до сброса или запросить увеличение квотыТратить бюджет повторов на дневную квоту
RESOURCE_EXHAUSTED из-за лимита по расходамРаспределить дорогие вызовы во времени; понизить thinking_level или объём выводаСчитать, что это лимит RPM

Python SDK от Google уже повторяет 429 и 5xx до четырёх раз, начиная примерно с 1 секунды и с потолком в 60 секунд (устранение неполадок). Если обернуть его в собственный цикл повторов, один сбой может превратиться в дюжину запросов и больше. Пусть повторами управляет один слой. Общее руководство по повторам при 429 (на английском) описывает заголовки и тайминги задержек, а обработка ошибок AI API (на английском) содержит код задержек и автоматического выключателя (circuit breaker).

В Ofox. 429 от шлюза (type rate_limit_error в руководстве по обработке ошибок) — это отдельный лимит, не связанный с квотой проекта Google. В документации Ofox по лимитам указано значение по умолчанию 100 RPM, которое считается суммарно по всем ключам команды (перепроверено 19 ноября 2026 года). Чтобы запросить более высокий лимит, можно написать в Ofox по электронной почте, как описано на той странице. В наших тестах 429 не возникал.

Проверка. Логируйте точный code при каждом 429. Если quota_exceeded продолжает появляться после добавления задержек, проблема в квоте, а не в характере трафика.

Ошибки уровня рассуждений: minimal и xhigh

Модели Gemini 4 поддерживают разные уровни рассуждений. В руководстве Google по рассуждениям указано:

МодельПо умолчаниюПоддерживаемые уровни
gemini-4-carbonmediumlow, medium, high
gemini-4-argonmediumlow, medium, high
gemini-4-neonhighlow, medium, high, xhigh
gemini-4-hydrogenhighlow, medium, high, xhigh

minimal не поддерживается ни одной моделью Gemini 4. В чек-листах миграции Neon и Hydrogen сказано, что обе модели отклоняют minimal с ошибкой. Руководство Google по рассуждениям также отмечает minimal как неподдерживаемый для gemini-3.8-flash, поэтому конфигурацию, скопированную со старой модели, которая его принимала, нужно изменить так же. По данным Google, Carbon и Argon ограничены уровнем high, но точное сообщение об ошибке для xhigh на этих моделях Google не публикует.

Исправление. Явно сопоставьте старые настройки: minimal заменяется на low, а xhigh на Carbon и Argon — на high. Перед отправкой проверяйте уровень в своём коде с учётом ID модели.

Что сделал шлюз. Наши тесты через Ofox показывают, почему не стоит рассчитывать, что сервер отловит эту ошибку:

Запрос (Ofox, 2026-11-19, по одному запуску)Результат
Hydrogen, Chat Completions reasoning_effort: "minimal"200, без ошибки; 20 токенов рассуждений
Hydrogen, нативный thinkingLevel: "minimal"200, без ошибки; 22 токена рассуждений
Argon, Chat Completions reasoning_effort: "xhigh"200, без ошибки; 157 токенов рассуждений
Argon, нативный thinkingLevel: "xhigh"200, без ошибки; 131 токен рассуждений
Hydrogen, reasoning_effort: "banana"400 INVALID_ARGUMENT (см. выше)

Значения, которые Google документирует как недопустимые, были приняты без ошибки, но это не значит, что они сработали. В ответах нет ничего, что показывало бы, какой уровень был применён. Шлюз мог отбросить значение или сопоставить его с поддерживаемым. На том же промпте запуски Hydrogen без настройки рассуждений использовали от 22 до 82 токенов рассуждений, а два запуска с minimal — 20 и 22, так что по числу токенов в единичных запусках нельзя понять, что произошло. Базовый запуск для Argon мы не делали вовсе. Выдуманное значение было отклонено вышестоящим сервисом. Считайте это единичным наблюдением на одном маршруте в один день. Не полагайтесь на такое поведение: код, который отправляет minimal только потому, что шлюз его принял, может сломаться при прямом обращении к Google. Руководство Ofox по рассуждениям Gemini описывает поля thinkingLevel и reasoning_effort. О выборе уровня под задачу читайте в статье Уровни рассуждений Gemini 4.

Пустые или обрезанные ответы: общее окно в 1M

Симптом. HTTP 200, но текст пустой или обрезан. Нативный generateContent показывает finishReason: "MAX_TOKENS", Chat Completions — finish_reason: "length", ресурс Interactions — статус incomplete.

Причина. В Gemini 4 max_output_tokens ограничивает рассуждения и видимый ответ вместе. Руководство Google по длинной генерации описывает именно этот симптом: статус incomplete с пустым текстом означает “the model used all tokens on thinking.” (модель израсходовала все токены на рассуждения). Лимит, перенесённый из старого приложения, например 8 192, делает такой исход гораздо вероятнее, особенно на Neon и Hydrogen, где по умолчанию стоит high.

Мы воспроизвели это на Hydrogen через Ofox с арифметическим вопросом в одну строку:

МаршрутНастройкаРезультат
Chat Completionsmax_tokens: 16200, content: "", finish_reason: "length", 13 из 16 completion-токенов ушли на рассуждения
Нативный generateContentmaxOutputTokens: 16200, candidate без parts, finishReason: "MAX_TOKENS", thoughtsTokenCount: 13

Запрос не завершился ошибкой и был оплачен. Не хватает только ответа. Если приложение проверяет лишь HTTP-статус, пользователь увидит пустой «успешный» результат.

Исправление.

  • Уберите низкие жёстко заданные лимиты. Google рекомендует не меньше 32 768 для Carbon. Для Neon и Hydrogen оставьте значение по умолчанию 65 536 или не передавайте поле вовсе.
  • Чтобы тратить меньше токенов, понизьте thinking_level. В руководстве Google по длинной генерации сказано, что снижение max_output_tokens не делает рассуждения модели короче, а лишь раньше обрывает ответ.
  • Для вывода длиннее 64K токенов задайте background: true и max_output_tokens больше 65 536, но не больше 1 048 576 за вычетом входных токенов.

Ограничения общего окна. Вход, рассуждения и вывод делят одно окно в 1 048 576 токенов. В Google, если вход плюс max_output_tokens превышает окно, API урезает лимит вывода до оставшегося места, а не отклоняет запрос (руководство по рассуждениям). Наши запросы через Ofox с max_tokens: 2000000 (Chat Completions) и maxOutputTokens: 2000000 (нативный) были приняты без ошибки, и модель ответила нормально; какой лимит применён на деле, по ответу не видно. Если вход сам по себе больше окна, это жёсткая ошибка. В руководстве Ofox по Gemini указаны 400 INVALID_ARGUMENT и сообщение The input token count exceeds the maximum number of tokens allowed 1048576. Этот случай мы не воспроизводили: тестовый вход в миллион токенов вышел бы за наш тестовый бюджет.

Лимиты одного шага. Один шаг (hop) в обычном, не фоновом режиме ограничен 65 536 токенами на Neon и Hydrogen, но 32 768 для непотоковых вызовов на Carbon и Argon. Когда шаг упирается в лимит, а бюджет ещё не исчерпан, статус становится requires_continuation. SDK версий ниже Python 2.34.0, JavaScript 2.32.0, Go 1.77.0, Java 1.80.0 и .NET 1.28.0 не продолжают такие interaction автоматически. Обновите SDK или отправьте следующий шаг с previous_interaction_id и continuation_token.

Проверка. При каждой проверке ответа смотрите на сигнал завершения (status == "completed", finishReason == "STOP" или finish_reason == "stop") и на то, что текст не пустой, а не только на HTTP-статус.

Фоновые и долгие interaction

Длинным задачам на Carbon и Neon место в фоновом выполнении. Руководство Google по фоновому выполнению и руководство по длинной генерации описывают такие сбои:

СимптомПричинаИсправление
400 при созданииbackground: true вместе с store: falseОставьте store: true (значение по умолчанию) для фоновых задач
400 при продолжении диалога следующим ходомПредыдущий interaction ещё в статусе in_progressДождитесь completed, прежде чем передавать его ID как previous_interaction_id
Статус failedОшибка во время выполнения (примеры Google: сбой инструмента, лимиты) или задача шла дольше 24 часовПовторите один раз; при повторном сбое отправьте ID interaction в поддержку
Статус failed с кодом безопасности в errorsКонтент заблокирован во время задачиСм. раздел о безопасности; повтор с тем же входом не поможет
Таймаут клиента, состояние задачи неизвестноHTTP-таймаут короче времени рассужденийОпросите сохранённый ID interaction, прежде чем отправлять заново
404 на GETInteraction удалёнЗабирайте результаты до удаления

Для сложных промптов на Carbon и Neon Google рекомендует HTTP-таймауты не менее 15 минут или фоновое выполнение. Отменённые и завершившиеся сбоем interaction оплачиваются за работу, выполненную до остановки. Поэтому клиент, который получил таймаут и отправил запрос заново, может заплатить за одну задачу дважды. Сохраняйте ID interaction сразу после создания задачи.

Ошибки вызова инструментов: подписи рассуждений и некорректные вызовы

На странице ошибок API Google перечислены такие коды ошибок генерации: malformed_function_call, malformed_tool_call, unexpected_tool_call, too_many_tool_calls и missing_thought_signature.

MALFORMED_FUNCTION_CALL после миграции. Руководства по Neon и Hydrogen предупреждают: не просите модель через системные инструкции выдавать вызовы инструментов в виде JSON обычным текстом, если инструменты не объявлены, потому что это может привести к MALFORMED_FUNCTION_CALL. Исправление — объявить инструменты через поля function calling в API или использовать структурированный вывод для JSON.

missing_thought_signature. Подписи рассуждений (thought signatures) переносят состояние рассуждений модели между ходами. Правила Google:

  • В Interactions API с store: true и previous_interaction_id подписи обрабатывает сервер. Ничего делать не нужно.
  • В режиме без сохранения состояния отправляйте каждый блок thought в точности в том виде, в каком он пришёл, включая блоки предыдущей модели после смены модели и подписи на блоках вызова и результата встроенных инструментов.
  • В истории generateContent, которую ведёт клиент, возвращайте предыдущие ходы модели и подписи без изменений и не копируйте одну подпись на параллельные части functionCall.

Мы отправили Hydrogen через Ofox нативную историю generateContent с частью functionCall без подписи. Запрос был принят без ошибки, и модель ответила на основе результата инструмента. Один запуск на одном маршруте не показывает, выполнялась ли проверка подписи или история была обработана как-то иначе, поэтому не считайте это разрешением отбрасывать подписи. Чек-листы миграции Google требуют возвращать подписи без изменений. Пошаговое исправление по полям для REST, SDK и адаптеров совместимости — в статье Исправление missing thought_signature. В наших тестах ответ Chat Completions от Ofox передавал подпись в message.reasoning_details (type reasoning.encrypted). Сохраняйте этот объект, если ваш фреймворк повторно отправляет ходы assistant.

Блокировки безопасности и цитирования (recitation)

Симптом. В руководстве Google по настройкам безопасности сказано, что заблокированный вход или ответ “fails with an HTTP 400 error” (завершается ошибкой HTTP 400), а заблокированный контент не возвращается. Пример из документации:

{"error": {"code": "safety",
  "message": "Request blocked due to safety violations (harmful content). Please modify your input and retry."}}

Для блокировки входа используются коды jailbreak, prohibited_content или blocklist, а сообщения начинаются с Input blocked:. На странице ошибок API Google перечислены и другие коды блокировки генерации, в том числе recitation, language, spii и content_blocked. В фоновом режиме статус interaction становится failed, а код появляется в его списке errors. При потоковой передаче он приходит как событие error.

Исправление. Считайте это проблемой контента, а не сбоем сервиса, и не повторяйте запрос автоматически. Настраиваемые фильтры безопасности по умолчанию выключены (Off) в Gemini 2.5 и более поздних моделях, а некоторые категории вреда блокируются всегда, независимо от настроек, так что ослабление порогов снимет не каждую блокировку. Переформулируйте легитимный запрос; не пытайтесь обойти фильтр. BlockedReason.OTHER означает, что запрос может нарушать условия использования или не поддерживается. Для RECITATION Google советует сделать промпт и контекст более уникальными. Его прежний совет про temperature к Gemini 4 неприменим: модели Gemini 4 игнорируют temperature.

Проверка. Логируйте код вместе с ID запроса, чтобы в мониторинге отличать блокировки контента от сбоев 5xx.

Ошибки миграции и устаревания

Большинство ошибок 400 сразу после обновления вызваны конфигурацией, которая работала на Gemini 3.x. Ниже — задокументированные несовместимые изменения для Carbon, Neon и Hydrogen из трёх чек-листов миграции Google:

Старая настройкаПоведение в Gemini 4Исправление
temperature, top_p, top_kИгнорируются, в ответе есть заголовки с предупреждением об устаревании (устранение неполадок); значения вне диапазона возвращают 400 (руководства по Neon и Hydrogen); Google сообщает, что в будущем релизе будет возвращаться 400Удалите все три
cached_content, caches.createЯвное кеширование не поддерживаетсяУдалите; неявное кеширование применяется к промптам от 4 096 токенов
thinking_level: "minimal"Отклоняется на Neon и HydrogenИспользуйте low
max_output_tokens: 8192Рассуждения съедают большую часть лимитаПоднимите до 32 768–65 536
candidate_count больше 1Не поддерживается в Gemini 3 и 4Удалите

Что касается параметров сэмплирования: наши запросы к Hydrogen через Ofox с temperature: 5 были приняты без ошибки (HTTP 200) и через Chat Completions, и через нативный маршрут. В полученных полных заголовках ответа не было заголовка с предупреждением об устаревании, поэтому по ответам нельзя понять, дошло ли значение до Google вообще. В руководстве Google по Hydrogen сказано, что значения вне диапазона возвращают 400. Удалите параметр, чтобы один и тот же код вёл себя одинаково на любом маршруте.

Устаревшие ID моделей. На странице устаревания Google по состоянию на 19 ноября 2026 года не указана дата отключения ни для одной модели Gemini 4. Сюрпризы случаются со старыми ID. gemini-3.7-flash и gemini-3.5-flash уже автоматически перенаправляются на более новые модели Flash. С 1 декабря 2026 года все запросы API к gemini-2.5-pro будут перенаправляться на gemini-3.8-flash и тарифицироваться по ценам 3.8 Flash. Перенаправление — не ошибка, но оно меняет поведение модели и стоимость без какой-либо ошибки, которая бы об этом предупредила. Фиксируйте и логируйте поле modelVersion (Ofox возвращает его как model или modelVersion), чтобы заметить скрытую смену маршрута. Если вы уходите с 3.8 Flash, в руководстве по переходу с Gemini 3.8 Flash на Hydrogen есть план тестирования «до и после».

Какие ошибки повторять

Повторять с задержкойИсправить запрос, не повторятьЖдать ресурсов или оплаты
429 по частоте / too many requests, 500, 503, 504, 408, статус failed (один раз)Любой 400, 401, 403, 404, коды блокировки безопасности и генерации429 quota_exceeded, 402 payment_required, RESOURCE_EXHAUSTED из-за лимита по расходам

Это совпадает с рекомендацией Google не повторять 400, 402 и 403, а также с таблицей Ofox, где 400, 401, 402, 403 и 404 не подлежат повтору, а 429, 500, 502 и 503 подлежат. Сравнение кодов статусов у разных провайдеров — в справочнике кодов ошибок LLM API.

Что мы протестировали, а что нет

Протестировано через Ofox 19 ноября 2026 года, по одному запуску на случай (плюс два повторных запуска случая с temperature, чтобы получить полные заголовки): неверные ID, модели вне каталога, ID без префикса, три значения уровня рассуждений (minimal, xhigh и недопустимое) в пяти запросах, слишком большие и крошечные лимиты вывода, temperature вне диапазона, история инструментов без подписи и недействительный ключ (401, type invalid_api_key, сообщение Invalid or expired API key). Промпты были тривиальными (“Reply with the single word OK” и арифметический вопрос в одну строку). Исходные запросы и ответы сохранены, ключ скрыт.

Не тестировалось: любые вызовы Carbon или Neon на эндпоинте Google, 403 на бесплатном уровне, реальные 429, блокировки безопасности, фоновые задачи и переполнение контекста. Эти разделы опираются на документацию Google, а сообщения цитируются только там, где их приводят Google или Ofox. Ответ 200 в наших запусках означает лишь, что запрос не был отклонён. Поведение шлюза может измениться без предупреждения, поэтому перепроверьте случаи с параметрами на своём маршруте.

Если вы ещё только подключаетесь, начните с руководства по настройке Hydrogen API, руководства по настройке Carbon API или руководства по Neon API, а сюда возвращайтесь, когда запрос завершится ошибкой.

Документация по теме

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

Почему запрос к Gemini 4 завершается успешно, но текста в ответе нет?
Рассуждения и видимый ответ расходуют общий лимит max_output_tokens. При низком лимите модель может потратить весь бюджет на рассуждения. В нашем тесте через Ofox запрос к Hydrogen с max_tokens 16 вернул HTTP 200 с пустым content и finish_reason "length". Увеличьте лимит (Google рекомендует не меньше 32 768 для Carbon и значение по умолчанию 65 536 для Neon и Hydrogen) или понизьте thinking_level.
Можно ли вызвать Gemini 4 Carbon или Neon через Ofox?
По состоянию на 19 ноября 2026 года нельзя. В нашем тесте оба ID вернули на Ofox 404 model_not_found. В каталоге Ofox есть Gemini 4 Hydrogen и Gemini 4 Argon. Для Carbon и Neon используйте платный уровень Google.