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.
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ável | Primeira verificação | Seção |
|---|---|---|---|
404 model_not_found | Erro de digitação, sufixo inventado ou um modelo que sua rota não oferece | Copie o ID da lista de modelos atual do provedor | ID do modelo |
403 PERMISSION_DENIED mencionando verificação, nível gratuito ou pagamento | Nível do projeto ou situação de cobrança | Status do projeto no AI Studio, não a chave | Nível pago |
402 payment_required | Créditos pré-pagos esgotados | Saldo de cobrança; não tente de novo | Nível pago |
429 com rate_limit_exceeded / too_many_requests | Pico de requisições por minuto | Concorrência e taxa de tokens | 429 |
429 com quota_exceeded | Cota diária esgotada | Aguarde a renovação; novas tentativas não ajudam | 429 |
400 mencionando thinking_level | Nível inválido para aquele modelo | Tabela de níveis por modelo | Níveis de raciocínio |
400 depois de migrar do Gemini 3.x | Configuração antiga de amostragem, cache ou instruções de ferramentas | Checklist de migração | Migração |
HTTP 200, texto vazio, MAX_TOKENS / length / incomplete | O raciocínio consumiu o orçamento de saída | max_output_tokens e thinking_level | Orçamento de saída |
Status requires_continuation | Uma etapa em primeiro plano atingiu o limite por requisição | Versão do SDK ou loop de continuação | Orçamento de saída |
Job em segundo plano failed ou travado | Falha no servidor, limite de 24 horas ou store=false | Status da interaction e lista errors | Segundo plano |
missing_thought_signature, malformed_function_call | Histórico de ferramentas alterado ou ferramentas não declaradas | Como o histórico é reenviado | Chamadas de ferramentas |
400 com code safety, prohibited_content | Filtro de conteúdo | O prompt e suas configurações de segurança | Seguranç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 enviada | Endpoint | Resultado |
|---|---|---|
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 (sem o prefixo google/) | /v1/chat/completions | 200, 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.io/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:
| Sinal | Significado | Correção |
|---|---|---|
403 com FREE_TIER_VERIFICATION_REQUIRED, status Verification needed | O projeto do nível gratuito precisa de verificação | Verifique com um dispositivo móvel ou configure a cobrança |
| Status Free tier unavailable | O projeto não é elegível para o nível gratuito | Vincule uma conta ativa do Cloud Billing |
Status Payment needed, ou 403 citando saldo em aberto | Conta de cobrança em atraso | Quite o saldo; o acesso volta automaticamente |
403 dizendo que a chave foi denunciada como vazada | O Google bloqueou a chave | Crie uma nova chave e mantenha-a fora do código do cliente |
402 payment_required | Créditos pré-pagos esgotados | Adicione 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:
| Code | Faça | Não faça |
|---|---|---|
rate_limit_exceeded, too_many_requests | Backoff exponencial com jitter; reduza a concorrência | Repetir na hora, em paralelo |
quota_exceeded | Pause o job até a renovação ou peça mais cota | Gastar o orçamento de novas tentativas em uma cota diária |
RESOURCE_EXHAUSTED por limite de gastos | Espalhe as chamadas caras; reduza o thinking_level ou o tamanho da saída | Supor 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:
| Modelo | Padrão | Níveis aceitos |
|---|---|---|
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 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:
| Rota | Configuração | Resultado |
|---|---|---|
| Chat Completions | max_tokens: 16 | 200, content: "", finish_reason: "length", 13 dos 16 tokens de completion foram de raciocínio |
generateContent nativo | maxOutputTokens: 16 | 200, 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 omax_output_tokensnão faz o modelo raciocinar de forma mais concisa; só corta a resposta mais cedo. - Para saídas acima de 64K tokens, defina
background: trueemax_output_tokensacima 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:
| Sintoma | Causa | Correção |
|---|---|---|
400 ao criar | background: true com store: false | Mantenha store: true (o padrão) em jobs em segundo plano |
400 ao encadear o turno seguinte | A interaction anterior ainda está in_progress | Aguarde completed antes de passar o ID dela como previous_interaction_id |
Status failed | Erro durante a execução (exemplos do Google: falha de ferramenta, limites de taxa) ou o job passou de 24 horas | Tente de novo uma vez; se falhar outra vez, envie o ID da interaction ao suporte |
Status failed com um code de segurança em errors | Conteúdo bloqueado durante o job | Veja a seção de segurança; repetir a mesma entrada não ajuda |
| Timeout no cliente, estado do job desconhecido | Timeout HTTP menor que o tempo de raciocínio | Consulte o ID da interaction salvo antes de reenviar |
404 no GET | A interaction foi excluída | Recupere 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: trueeprevious_interaction_id, o servidor cuida das assinaturas. Você não precisa fazer nada. - No modo sem estado, reenvie cada bloco
thoughtexatamente 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
generateContentgerenciados pelo cliente, devolva os turnos anteriores do modelo e as assinaturas sem alterações, e não copie uma mesma assinatura para partesfunctionCallparalelas.
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 antiga | Comportamento no Gemini 4 | Correção |
|---|---|---|
temperature, top_p, top_k | Ignorados, 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 400 | Remova os três |
cached_content, caches.create | Cache explícito não suportado | Remova; o cache implícito vale para prompts a partir de 4.096 tokens |
thinking_level: "minimal" | Rejeitado no Neon e no Hydrogen | Use low |
max_output_tokens: 8192 | O raciocínio consome a maior parte do limite | Aumente para 32.768–65.536 |
candidate_count acima de 1 | Não suportado no Gemini 3 e 4 | Remova |
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 backoff | Corrigir a requisição, não repetir | Aguardar 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ção | 429 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
- Tratamento de erros e novas tentativas na Ofox
- Limites de taxa da Ofox
- Guia da família Gemini e erros comuns na Ofox
- API nativa do Gemini na Ofox
- Gemini 4 Hydrogen na Ofox (preço atual e protocolos suportados)
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.


