Ошибки 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/completions | 404 model_not_found |
google/gemini-4-hydrogen-preview | /gemini/v1beta/models/...:generateContent | 404 model_not_found |
google/gemini-4-carbon | /v1/chat/completions | 404 model_not_found |
google/gemini-4-neon | /v1/chat/completions | 404 model_not_found |
gemini-4-hydrogen (без префикса google/) | /v1/chat/completions | 200, поле 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.ai/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-carbon | medium | low, medium, high |
gemini-4-argon | medium | low, medium, high |
gemini-4-neon | high | low, medium, high, xhigh |
gemini-4-hydrogen | high | low, 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 Completions | max_tokens: 16 | 200, content: "", finish_reason: "length", 13 из 16 completion-токенов ушли на рассуждения |
Нативный generateContent | maxOutputTokens: 16 | 200, 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 на GET | Interaction удалён | Забирайте результаты до удаления |
Для сложных промптов на 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, а сюда возвращайтесь, когда запрос завершится ошибкой.
Документация по теме
- Обработка ошибок и повторы в Ofox
- Лимиты Ofox
- Руководство Ofox по семейству Gemini и типичным ошибкам
- Нативный Gemini API в Ofox
- Gemini 4 Hydrogen в Ofox (актуальная цена и поддерживаемые протоколы)
Часто задаваемые вопросы
- Почему запрос к 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.


