Erros na API do Gemini 4: como diagnosticar falhas no Carbon, Neon e Hydrogen

Diagnostique erros da API do Gemini 4 Carbon, Neon e Hydrogen: IDs de modelo errados, bloqueios do nível gratuito, 429, níveis de raciocínio, respostas vazias, chamadas de ferramentas e bloqueios de segurança.

Desenho em linha de um quadro de disjuntores aberto, com duas colunas de chaves; uma delas, laranja, desarmou.

A maioria dos erros da API do Gemini 4 cai em cinco grupos: ID de modelo ou rota errados, nível do projeto (Carbon e Neon só estão disponíveis no nível pago), cota (429), parâmetros não suportados (minimal, ou xhigh no Carbon) e respostas que tecnicamente dão certo, mas vêm sem resposta porque o raciocínio consumiu o max_output_tokens. Descubra em qual grupo você está pelo status HTTP, pelo code do erro e pelo formato da resposta. Uma nova chave de API resolve apenas um caso bem específico: chave vazada ou bloqueada.

Este guia cobre o Gemini 4 Carbon, Neon e Hydrogen. O Argon tem um guia separado, o passo a passo de erros da API do Gemini 4 Argon, e este artigo não repete o modelo de registro de incidentes nem os casos de teste sintéticos de lá. As informações do Google abaixo vêm da documentação da API do Gemini, conferida em 19 de novembro de 2026 (os links para a documentação do Google levam a páginas em inglês). Os resultados da Ofox vêm de 21 requisições reais que enviamos naquele dia para google/gemini-4-hydrogen e google/gemini-4-argon pela Ofox, uma execução por caso (custo total estimado abaixo de US$ 0,05). Carbon e Neon não estão disponíveis na Ofox (catálogo verificado em 19 de novembro de 2026), então todos os exemplos de Carbon e Neon aqui usam a API nativa do Google.

Este artigo é publicado pela Ofox. Quando um resultado pelo gateway difere da documentação do Google, mostramos os dois, e a diferença não é apresentada como regra para o endpoint do próprio Google.

Comece pelo sintoma

Use a primeira linha que corresponder. Cada linha leva à seção com a correção e a etapa de verificação.

O que você vêCausa mais provávelPrimeira verificaçãoSeção
404 model_not_foundErro de digitação, sufixo inventado ou um modelo que sua rota não ofereceCopie o ID da lista de modelos atual do provedorID do modelo
403 PERMISSION_DENIED mencionando verificação, nível gratuito ou pagamentoNível do projeto ou situação de cobrançaStatus do projeto no AI Studio, não a chaveNível pago
402 payment_requiredCréditos pré-pagos esgotadosSaldo de cobrança; não tente de novoNível pago
429 com rate_limit_exceeded / too_many_requestsPico de requisições por minutoConcorrência e taxa de tokens429
429 com quota_exceededCota diária esgotadaAguarde a renovação; novas tentativas não ajudam429
400 mencionando thinking_levelNível inválido para aquele modeloTabela de níveis por modeloNíveis de raciocínio
400 depois de migrar do Gemini 3.xConfiguração antiga de amostragem, cache ou instruções de ferramentasChecklist de migraçãoMigração
HTTP 200, texto vazio, MAX_TOKENS / length / incompleteO raciocínio consumiu o orçamento de saídamax_output_tokens e thinking_levelOrçamento de saída
Status requires_continuationUma etapa em primeiro plano atingiu o limite por requisiçãoVersão do SDK ou loop de continuaçãoOrçamento de saída
Job em segundo plano failed ou travadoFalha no servidor, limite de 24 horas ou store=falseStatus da interaction e lista errorsSegundo plano
missing_thought_signature, malformed_function_callHistórico de ferramentas alterado ou ferramentas não declaradasComo o histórico é reenviadoChamadas de ferramentas
400 com code safety, prohibited_contentFiltro de conteúdoO prompt e suas configurações de segurançaSegurança

Leia o formato do erro antes da mensagem

O Google e um gateway como a Ofox formatam erros de maneiras diferentes. Confira quem respondeu antes de agir com base no texto.

A Interactions API do Google retorna um objeto error com um code legível por máquina e uma message, segundo a referência de erros da API do Google:

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

No streaming, o mesmo objeto chega como um evento SSE com "event_type": "error". Um stream pode começar com HTTP 200 e ainda falhar depois, então o leitor do stream precisa tratar eventos de erro. A API legada generateContent usa o estilo antigo de RPC do Google, com status como INVALID_ARGUMENT e RESOURCE_EXHAUSTED; por isso as páginas de solução de problemas do Google mostram os dois estilos de nome.

O gateway da Ofox produziu dois formatos nos nossos testes. Quando o ID do modelo não estava no catálogo do gateway, o próprio gateway respondeu com seu corpo de erro (ID da requisição encurtado). A mensagem tem o mesmo formato da linha sobre ID digitado errado no guia do Gemini da Ofox:

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

Quando a requisição chegou ao lado do Google (a Ofox oferece o Gemini via Vertex AI, segundo o guia do Gemini da Ofox) e foi rejeitada lá, o texto do serviço upstream voltou dentro do envelope do gateway:

{"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"}}

Um nome de tipo google.cloud.aiplatform na mensagem indica que o serviço do modelo upstream rejeitou o valor. Uma mensagem Model '<id>' not found significa que o gateway não reconheceu o ID do modelo.

O guia de tratamento de erros da Ofox documenta os códigos de status e quais deles podem ser repetidos. O corpo de erro de exemplo nesse guia tem "code": "invalid_api_key" e "type": "authentication_error", e a tabela lista o type do 404 como not_found_error. Os corpos que recebemos em 19 de novembro de 2026 tinham outro formato: o 401 veio com "code": 401 e "type": "invalid_api_key", e os 404 com "code": 404 e "type": "model_not_found". Se o seu handler decide o caminho com base nesses campos, verifique tanto code quanto type e teste com um erro capturado na sua própria rota.

404 model not found: o ID ou a rota está errado

Sintoma. Google: 404 com code model_not_found. Ofox: 404 com type model_not_found e a mensagem Model '<id>' not found.

Causa. Os quatro IDs do Gemini 4 na API do Google são exatamente gemini-4-carbon, gemini-4-neon, gemini-4-hydrogen e gemini-4-argon (página de modelos). Nenhum tem sufixo -preview ou -latest. A outra causa comum é uma rota que simplesmente não oferece o modelo.

Nossas requisições pela Ofox em 19 de novembro de 2026 (uma execução cada):

String de modelo enviadaEndpointResultado
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 (sem o prefixo google/)/v1/chat/completions200, campo model da resposta google/gemini-4-hydrogen

Correção. No Google, use o ID sem prefixo. Na Ofox, use google/gemini-4-hydrogen ou google/gemini-4-argon. A forma sem prefixo também funcionou no nosso teste, e o guia do Gemini da Ofox diz que o prefixo é opcional. Para Carbon ou Neon, use um projeto do Google no nível pago. Mudar a grafia não faz aparecer um modelo que o gateway não lista.

Verificação. Liste os modelos pelo mesmo endpoint e com a mesma chave que o seu app usa: GET https://generativelanguage.googleapis.com/v1beta/models no Google ou GET https://api.ofox.ai/v1/models na Ofox. O Google avisa que models.list só verifica se a chave existe. Um 200 do endpoint de listagem não prova que a inferência está habilitada para o projeto, então confirme com uma pequena chamada de geração.

Carbon e Neon falham em um projeto do nível gratuito

Sintoma. Uma requisição que funciona com o Hydrogen falha quando você troca o modelo para Carbon ou Neon. Sinais comuns são um 403 PERMISSION_DENIED, o status de projeto Free tier unavailable ou Payment needed no AI Studio, ou um erro de cota em um projeto que nunca teve cobrança.

Causa. O guia do Carbon afirma que o Carbon “is not available on the Free tier” (não está disponível no nível gratuito). O guia do Neon diz que o Neon está “available on the paid tier only” (disponível apenas no nível pago). O Hydrogen é o único modelo Gemini 4 com nível gratuito (preços). O Google não publica uma string de erro específica para um projeto do nível gratuito que chama Carbon ou Neon, então não compare pelo texto exato. Use o status e, em seguida, verifique o projeto.

O guia de solução de problemas do Google lista as variações de 403 no nível do projeto:

SinalSignificadoCorreção
403 com FREE_TIER_VERIFICATION_REQUIRED, status Verification neededO projeto do nível gratuito precisa de verificaçãoVerifique com um dispositivo móvel ou configure a cobrança
Status Free tier unavailableO projeto não é elegível para o nível gratuitoVincule uma conta ativa do Cloud Billing
Status Payment needed, ou 403 citando saldo em abertoConta de cobrança em atrasoQuite o saldo; o acesso volta automaticamente
403 dizendo que a chave foi denunciada como vazadaO Google bloqueou a chaveCrie uma nova chave e mantenha-a fora do código do cliente
402 payment_requiredCréditos pré-pagos esgotadosAdicione créditos ou ative a recarga automática; não tente de novo

Dois detalhes pegam muita gente. A elegibilidade é verificada por projeto do Google Cloud, então outra chave do mesmo projeto dá o mesmo resultado. Além disso, passar para o nível pago não libera a cota do nível gratuito; o uso pago é cobrado. Para um 429 do nível gratuito que informa limite 0, o diagnóstico do limite zero no nível gratuito do Gemini (em inglês) mostra como ler a métrica de cota. Ele foi escrito para modelos de imagem, mas a verificação do projeto é a mesma. O guia do nível gratuito da API do Gemini 4 explica o que o nível gratuito do Hydrogen inclui.

Verificação. No AI Studio, abra o projeto dono da chave e confirme o nível. Depois envie uma requisição curta ao Carbon ou ao Neon. Os preços do Carbon e do Argon dobram em 1º de dezembro de 2026 (guia do Carbon); os valores estão na análise da mudança de preço de dezembro.

429: separe um pico de uma cota esgotada

Sintoma. HTTP 429. Na Interactions API, o code é rate_limit_exceeded, too_many_requests ou quota_exceeded. No generateContent, é RESOURCE_EXHAUSTED.

Causa. A página de limites de taxa do Google estabelece três pontos:

  • Os limites valem por projeto, não por chave de API.
  • As cotas diárias de requisições são renovadas à meia-noite no horário do Pacífico.
  • Projetos pagos também têm um limite baseado em gastos em uma janela móvel de 10 minutos: US$ 10 no Tier 1 e US$ 200 nos Tiers 2 e 3. Ultrapassá-lo retorna 429 RESOURCE_EXHAUSTED, mesmo que sua taxa de requisições seja baixa.

O limite de gastos passa despercebido com facilidade no Gemini 4. Neon e Hydrogen usam raciocínio high por padrão, e os tokens de raciocínio são cobrados como tokens de saída. Poucas requisições longas e com muito raciocínio podem atingir o limite de gastos da janela do Tier 1 sem estourar nenhum limite de RPM.

Correção. Escolha a correção de acordo com o code:

CodeFaçaNão faça
rate_limit_exceeded, too_many_requestsBackoff exponencial com jitter; reduza a concorrênciaRepetir na hora, em paralelo
quota_exceededPause o job até a renovação ou peça mais cotaGastar o orçamento de novas tentativas em uma cota diária
RESOURCE_EXHAUSTED por limite de gastosEspalhe as chamadas caras; reduza o thinking_level ou o tamanho da saídaSupor que é o limite de RPM

O SDK de Python do Google já repete 429 e 5xx até quatro vezes, começando em cerca de 1 segundo, com teto de 60 segundos (solução de problemas). Se você envolver o SDK no seu próprio loop de novas tentativas, uma falha pode virar uma dúzia de requisições ou mais. Deixe uma única camada cuidar das novas tentativas. O guia geral de novas tentativas para 429 (em inglês) trata de cabeçalhos e do tempo de backoff, e o artigo sobre tratamento de erros em APIs de IA (em inglês) traz código de backoff e circuit breaker.

Na Ofox. Um 429 do gateway (type rate_limit_error no guia de tratamento de erros) é um limite separado da cota do projeto no Google. A documentação de limites de taxa da Ofox informa um padrão de 100 RPM, somando todas as chaves de uma equipe (conferido novamente em 19 de novembro de 2026). Você pode pedir um limite maior por e-mail à Ofox, como descrito nessa página. Não provocamos nenhum 429 nos nossos testes.

Verificação. Registre o code exato em cada 429. Se quota_exceeded continuar aparecendo depois de adicionar backoff, o problema é cota, não o padrão de tráfego.

Erros de nível de raciocínio: minimal e xhigh

Os modelos Gemini 4 não aceitam os mesmos níveis de raciocínio. O guia de raciocínio do Google lista:

ModeloPadrãoNíveis aceitos
gemini-4-carbonmediumlow, medium, high
gemini-4-argonmediumlow, medium, high
gemini-4-neonhighlow, medium, high, xhigh
gemini-4-hydrogenhighlow, medium, high, xhigh

minimal não é aceito em nenhum modelo Gemini 4. Os checklists de migração do Neon e do Hydrogen dizem que os dois modelos rejeitam minimal com erro. O guia de raciocínio do Google também lista minimal como não suportado no gemini-3.8-flash, então uma configuração copiada de um modelo mais antigo que o aceitava precisa da mesma mudança. O Google diz que Carbon e Argon vão no máximo até high, mas não publica a mensagem de erro exata para xhigh nesses modelos.

Correção. Converta as configurações antigas de forma explícita: minimal vira low, e xhigh vira high no Carbon e no Argon. Valide o nível no seu próprio código, de acordo com o ID do modelo, antes de enviar.

O que o gateway fez. Nossos testes na Ofox mostram por que não vale contar com o servidor para pegar esse erro:

Requisição (Ofox, 2026-11-19, uma execução cada)Resultado
Hydrogen, Chat Completions reasoning_effort: "minimal"200, sem erro; 20 tokens de raciocínio
Hydrogen, nativo thinkingLevel: "minimal"200, sem erro; 22 tokens de raciocínio
Argon, Chat Completions reasoning_effort: "xhigh"200, sem erro; 157 tokens de raciocínio
Argon, nativo thinkingLevel: "xhigh"200, sem erro; 131 tokens de raciocínio
Hydrogen, reasoning_effort: "banana"400 INVALID_ARGUMENT (mostrado acima)

Os valores que o Google documenta como inválidos foram aceitos sem erro, mas isso não significa que funcionaram. Nada nas respostas mostra qual nível foi aplicado. O gateway pode ter descartado o valor ou convertido para um nível aceito. Com o mesmo prompt, execuções do Hydrogen sem nenhuma configuração de raciocínio usaram entre 22 e 82 tokens de raciocínio, e as duas execuções com minimal usaram 20 e 22; portanto, a contagem de tokens de execuções únicas não diz o que aconteceu. Não fizemos nenhuma execução de referência com o Argon. Um valor inventado foi rejeitado no upstream. Trate isso como uma única observação de uma rota em um dia. Não conte com esse comportamento: um código que envia minimal porque o gateway aceitou pode quebrar quando você chamar o Google diretamente. O guia de raciocínio do Gemini da Ofox documenta os campos thinkingLevel e reasoning_effort. Para escolher o nível de acordo com a tarefa, veja níveis de raciocínio do Gemini 4.

Respostas vazias ou cortadas: a janela compartilhada de 1M

Sintoma. HTTP 200, mas o texto vem vazio ou cortado. O generateContent nativo mostra finishReason: "MAX_TOKENS", o Chat Completions mostra finish_reason: "length" e um recurso da Interactions mostra o status incomplete.

Causa. No Gemini 4, max_output_tokens limita raciocínio e saída visível somados. O guia de saídas longas do Google descreve exatamente esse sintoma: status incomplete com texto vazio significa “the model used all tokens on thinking.” (o modelo usou todos os tokens raciocinando). Um limite herdado de um app antigo, como 8.192, torna isso muito mais provável, principalmente no Neon e no Hydrogen, que usam high por padrão.

Reproduzimos isso no Hydrogen pela Ofox com uma pergunta de aritmética de uma linha:

RotaConfiguraçãoResultado
Chat Completionsmax_tokens: 16200, content: "", finish_reason: "length", 13 dos 16 tokens de completion foram de raciocínio
generateContent nativomaxOutputTokens: 16200, candidate sem parts, finishReason: "MAX_TOKENS", thoughtsTokenCount: 13

A requisição não falhou e foi cobrada. Só a resposta está faltando. Se o seu app verifica apenas o status HTTP, ele vai tratar uma resposta em branco como sucesso.

Correção.

  • Remova limites baixos fixos no código. O Google recomenda pelo menos 32.768 no Carbon. No Neon e no Hydrogen, mantenha o padrão de 65.536 ou omita o campo.
  • Para gastar menos tokens, reduza o thinking_level. O guia de saídas longas do Google diz que reduzir o max_output_tokens não faz o modelo raciocinar de forma mais concisa; só corta a resposta mais cedo.
  • Para saídas acima de 64K tokens, defina background: true e max_output_tokens acima de 65.536, até 1.048.576 menos os seus tokens de entrada.

Limites da janela compartilhada. Entrada, raciocínio e saída dividem uma única janela de 1.048.576 tokens. No Google, se a entrada mais o max_output_tokens ultrapassar a janela, a API reduz o limite de saída ao espaço restante em vez de rejeitar a requisição (guia de raciocínio). Nossas requisições pela Ofox com max_tokens: 2000000 (Chat Completions) e maxOutputTokens: 2000000 (nativo) foram aceitas sem erro e responderam normalmente; a resposta não mostra qual limite foi realmente aplicado. Uma entrada que sozinha ultrapassa a janela gera erro definitivo. O guia do Gemini da Ofox lista 400 INVALID_ARGUMENT com a mensagem The input token count exceeds the maximum number of tokens allowed 1048576. Não reproduzimos esse caso, porque uma entrada de teste com um milhão de tokens passaria do nosso orçamento de testes.

Limites por etapa. Uma única etapa (hop) em primeiro plano tem limite de 65.536 tokens no Neon e no Hydrogen, mas de 32.768 em chamadas sem streaming no Carbon e no Argon. Quando uma etapa atinge o limite com orçamento sobrando, o status é requires_continuation. SDKs anteriores a Python 2.34.0, JavaScript 2.32.0, Go 1.77.0, Java 1.80.0 e .NET 1.28.0 não continuam interactions em primeiro plano automaticamente. Atualize o SDK ou envie a próxima etapa com previous_interaction_id e continuation_token.

Verificação. Toda checagem de resposta deve testar o sinal de término (status == "completed", finishReason == "STOP" ou finish_reason == "stop") e se o texto não está vazio, e não apenas o status HTTP.

Execução em segundo plano e interactions de longa duração

Jobs longos de Carbon e Neon devem rodar em segundo plano. O guia de execução em segundo plano do Google e o guia de saídas longas documentam estas falhas:

SintomaCausaCorreção
400 ao criarbackground: true com store: falseMantenha store: true (o padrão) em jobs em segundo plano
400 ao encadear o turno seguinteA interaction anterior ainda está in_progressAguarde completed antes de passar o ID dela como previous_interaction_id
Status failedErro durante a execução (exemplos do Google: falha de ferramenta, limites de taxa) ou o job passou de 24 horasTente de novo uma vez; se falhar outra vez, envie o ID da interaction ao suporte
Status failed com um code de segurança em errorsConteúdo bloqueado durante o jobVeja a seção de segurança; repetir a mesma entrada não ajuda
Timeout no cliente, estado do job desconhecidoTimeout HTTP menor que o tempo de raciocínioConsulte o ID da interaction salvo antes de reenviar
404 no GETA interaction foi excluídaRecupere os resultados antes de excluir

O Google recomenda timeouts HTTP de pelo menos 15 minutos para prompts difíceis no Carbon e no Neon, ou execução em segundo plano. Interactions canceladas e com falha são cobradas pelo trabalho feito até pararem. Um cliente que dá timeout e reenvia pode, portanto, pagar duas vezes pela mesma tarefa. Salve o ID da interaction assim que criar o job.

Erros em chamadas de ferramentas: assinaturas de raciocínio e chamadas malformadas

A página de erros da API do Google lista estes códigos de erro de geração: malformed_function_call, malformed_tool_call, unexpected_tool_call, too_many_tool_calls e missing_thought_signature.

MALFORMED_FUNCTION_CALL depois da migração. Os guias do Neon e do Hydrogen alertam contra pedir ao modelo, por instruções de sistema, que emita chamadas de ferramentas como JSON em texto puro quando nenhuma ferramenta foi declarada, porque isso pode retornar MALFORMED_FUNCTION_CALL. Corrija declarando as ferramentas pelos campos de function calling da API ou usando saída estruturada para JSON.

missing_thought_signature. As assinaturas de raciocínio (thought signatures) carregam o estado de raciocínio do modelo entre turnos. As regras do Google:

  • Na Interactions API com store: true e previous_interaction_id, o servidor cuida das assinaturas. Você não precisa fazer nada.
  • No modo sem estado, reenvie cada bloco thought exatamente como recebeu, incluindo os blocos do modelo anterior após uma troca de modelo e as assinaturas nos blocos de chamada e de resultado de ferramentas nativas.
  • Em históricos de generateContent gerenciados pelo cliente, devolva os turnos anteriores do modelo e as assinaturas sem alterações, e não copie uma mesma assinatura para partes functionCall paralelas.

Enviamos ao Hydrogen, pela Ofox, um histórico nativo de generateContent com uma parte functionCall sem assinatura. Ele foi aceito sem erro e respondeu com base no resultado da ferramenta. Uma execução em uma rota não mostra se a verificação de assinatura rodou ou se o histórico foi tratado de outra forma, então não interprete isso como permissão para descartar assinaturas. Os checklists de migração do Google mandam devolver as assinaturas sem alterações. Para um reparo campo a campo em REST, SDKs e adaptadores de compatibilidade, use a correção de missing thought_signature (em inglês). Na Ofox, a resposta do Chat Completions trouxe a assinatura em message.reasoning_details (type reasoning.encrypted) nos nossos testes. Preserve esse objeto se o seu framework reenvia os turnos do assistant.

Bloqueios de segurança e de recitação

Sintoma. O guia de configurações de segurança do Google diz que uma entrada ou resposta bloqueada “fails with an HTTP 400 error” (falha com um erro HTTP 400) e que o conteúdo bloqueado não é retornado. O exemplo documentado:

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

Bloqueios de entrada usam os codes jailbreak, prohibited_content ou blocklist, com mensagens que começam com Input blocked:. A página de erros da API do Google lista outros codes de geração bloqueada, incluindo recitation, language, spii e content_blocked. No modo em segundo plano, o status da interaction passa a failed e o code aparece na lista errors. No streaming, ele chega como um evento error.

Correção. Trate esses casos como problemas de conteúdo, não como indisponibilidade, e não repita automaticamente. Os filtros de segurança ajustáveis vêm desligados (Off) por padrão no Gemini 2.5 e posteriores, e alguns tipos de dano são sempre bloqueados, independentemente das configurações; afrouxar os limites não vai liberar todos os bloqueios. Reescreva a solicitação legítima; não tente contornar o filtro. BlockedReason.OTHER significa que a requisição pode violar os termos ou não ser suportada. Para RECITATION, o Google sugere deixar o prompt e o contexto mais originais. A antiga dica sobre temperatura não se aplica ao Gemini 4, que ignora temperature.

Verificação. Registre o code junto com o ID da requisição para distinguir, no monitoramento, bloqueios de conteúdo de falhas 5xx.

Erros de migração e descontinuação

A maioria dos erros 400 logo após um upgrade vem de configurações que funcionavam no Gemini 3.x. Estas são as mudanças incompatíveis documentadas para Carbon, Neon e Hydrogen, tiradas dos três checklists de migração do Google:

Configuração antigaComportamento no Gemini 4Correção
temperature, top_p, top_kIgnorados, com cabeçalhos de aviso de descontinuação (solução de problemas); valores fora do intervalo retornam 400 (guias do Neon e do Hydrogen); o Google diz que uma versão futura vai retornar 400Remova os três
cached_content, caches.createCache explícito não suportadoRemova; o cache implícito vale para prompts a partir de 4.096 tokens
thinking_level: "minimal"Rejeitado no Neon e no HydrogenUse low
max_output_tokens: 8192O raciocínio consome a maior parte do limiteAumente para 32.768–65.536
candidate_count acima de 1Não suportado no Gemini 3 e 4Remova

Sobre parâmetros de amostragem: nossas requisições pela Ofox ao Hydrogen com temperature: 5 foram aceitas sem erro (HTTP 200) tanto no Chat Completions quanto na rota nativa. Os cabeçalhos completos de resposta que capturamos não tinham cabeçalho de aviso de descontinuação, então as respostas não mostram se o valor chegou ao Google. O guia do Hydrogen do Google diz que valores fora do intervalo retornam 400. Remova o parâmetro para que o mesmo código se comporte igual em qualquer rota.

IDs de modelo descontinuados. A página de descontinuações do Google não lista data de desligamento para nenhum modelo Gemini 4 em 19 de novembro de 2026. As surpresas aparecem nos IDs mais antigos. gemini-3.7-flash e gemini-3.5-flash já são redirecionados automaticamente para modelos Flash mais novos. A partir de 1º de dezembro de 2026, todas as requisições de API para gemini-2.5-pro serão redirecionadas para gemini-3.8-flash e cobradas pelos preços do 3.8 Flash. O redirecionamento não é um erro, mas muda o comportamento do modelo e o custo sem nenhum erro para avisar. Fixe e registre o campo modelVersion (a Ofox o retorna como model ou modelVersion) para perceber uma mudança de rota silenciosa. Se você está saindo do 3.8 Flash, o guia de migração do Gemini 3.8 Flash para o Hydrogen traz um plano de testes de antes e depois.

Quais erros repetir

Repetir com backoffCorrigir a requisição, não repetirAguardar capacidade ou cobrança
429 de taxa / too many requests, 500, 503, 504, 408, status failed (uma vez)Qualquer 400, 401, 403, 404, codes de bloqueio de segurança e de geração429 quota_exceeded, 402 payment_required, RESOURCE_EXHAUSTED por limite de gastos

Isso coincide com a orientação do Google de não repetir 400, 402 ou 403 e com a tabela da Ofox, em que 400, 401, 402, 403 e 404 não devem ser repetidos e 429, 500, 502 e 503 podem ser. Para comparar códigos de status entre provedores, veja a referência de códigos de erro de APIs de LLM (em inglês).

O que testamos e o que não testamos

Testado pela Ofox em 19 de novembro de 2026, uma execução por caso (mais duas repetições do caso de temperatura para capturar os cabeçalhos completos): IDs errados, modelos fora do catálogo, o ID sem prefixo, três valores de nível de raciocínio (minimal, xhigh e um inválido) em cinco requisições, limites de saída enormes e minúsculos, uma temperatura fora do intervalo, um histórico de ferramentas sem assinatura e uma chave inválida (401, type invalid_api_key, mensagem Invalid or expired API key). Os prompts eram triviais (“Reply with the single word OK” e uma pergunta de aritmética de uma linha). As requisições e respostas brutas estão salvas, com a chave ocultada.

Não testado: qualquer chamada ao Carbon ou ao Neon no endpoint do Google, 403 do nível gratuito, 429 reais, bloqueios de segurança, jobs em segundo plano e estouro de contexto. Essas seções se baseiam na documentação do Google, e só citamos mensagens quando o Google ou a Ofox as publicam. Um 200 nas nossas execuções significa apenas que a requisição não foi rejeitada. O comportamento do gateway pode mudar sem aviso, então confira novamente os casos de parâmetros na sua própria rota.

Se você ainda está configurando o acesso, comece pelo guia de configuração da API do Hydrogen, pelo guia de configuração da API do Carbon ou pelo guia da API do Neon e volte aqui quando uma requisição falhar.

Documentação relacionada

Perguntas frequentes

Por que minha requisição ao Gemini 4 dá certo, mas não retorna texto?
O raciocínio e a saída visível dividem o mesmo max_output_tokens. Com um limite baixo, o modelo pode gastar todo o orçamento raciocinando. No nosso teste pela Ofox, max_tokens 16 no Hydrogen retornou HTTP 200 com content vazio e finish_reason "length". Aumente o limite (o Google recomenda pelo menos 32.768 no Carbon e o padrão de 65.536 no Neon e no Hydrogen) ou reduza o thinking_level.
Dá para chamar o Gemini 4 Carbon ou o Neon pela Ofox?
Não, em 19 de novembro de 2026. No nosso teste, os dois IDs retornaram 404 model_not_found na Ofox. O Gemini 4 Hydrogen e o Gemini 4 Argon estão listados. Para Carbon e Neon, use o nível pago do Google.