Erros na API do Gemini 4 Argon: como resolver 403, 404, 429 e respostas vazias

Comece pelo endpoint e pela resposta bruta, não por uma nova chave de API. Uma requisição ao Gemini 4 Argon pode falhar porque o cliente envia o esquema errado, o projeto não tem permissão, o recurso selecionado não existe ou uma cota foi atingida. Uma resposta vazia também pode indicar que a aplicação leu o campo errado ou que a interação ainda não terminou.

Este guia aborda a Gemini Developer API do Google, com exemplos da Interactions API conferidos na documentação oficial em 23 de outubro de 2026. Ele não comprova acesso via Vertex AI, proxy compatível com OpenAI, Ofox ou Antigravity. Os exemplos se baseiam na documentação; o exercício de diagnóstico abaixo é local e sintético, não uma chamada real bem-sucedida ao Argon.

Se o modelo não aparece no seletor de um aplicativo, comece pelo guia de acesso ao Gemini 4 Argon, em inglês. Se uma requisição à API de fato falhou, siga os passos a seguir.

Primeiro, diferencie um aviso do aplicativo de um erro da API

Uma mensagem como “currently available to Ultra plan subscribers” indica uma condição de acesso da conta ou do produto. Ela não basta para classificar uma resposta da API como HTTP 403. Registre onde apareceu: aplicativo Gemini, aplicativo ou CLI do Antigravity, AI Studio, seu backend ou um cliente de terceiros. A assinatura do aplicativo e a configuração do projeto da API precisam ser verificadas separadamente.

Antes de alterar qualquer coisa, reúna estas seis informações sobre a falha na API:

1. Host e caminho da requisição, sem a chave nem credenciais na query string.
2. ID exato do modelo e versão do SDK ou cliente.
3. Status HTTP, tipo de conteúdo da resposta e corpo do erro com dados sensíveis removidos.
4. Horário em UTC, tempo decorrido e número de tentativas já realizadas.
5. Projeto selecionado e indicação de uso de streaming ou execução em segundo plano.
6. Identificador da interação ou requisição, se retornado; compartilhe-o apenas pelo canal de suporte adequado.

Uma página HTML com 403 gerada pelo gateway da empresa exige uma investigação diferente de uma resposta JSON com permission_denied. Da mesma forma, uma linha de log com status=500 não é evidência suficiente de que o Google retornou HTTP 500: localize a resposta real do serviço upstream. Se nenhuma resposta HTTP chegou, investigue DNS, TLS, conectividade e timeout do cliente antes de atribuir um código de erro da API.

Use uma requisição mínima para localizar a camada que falha

O guia de início rápido do Argon usa o ID de modelo gemini-4-argon no endpoint de Interactions. Para esse diagnóstico, remova uploads de arquivos, ferramentas, estado de conversas anteriores e configurações extras de geração. Mantenha o mesmo projeto usado pela aplicação que falha.

O exemplo a seguir é um modelo de requisição cobrável para sua própria conta autorizada, não um comando que executamos contra o Argon. Ele exige curl e uma chave de API já disponível na variável GEMINI_API_KEY. Não cole a chave em um chamado nem a inclua em um repositório. O limite de 90 segundos no cliente é uma escolha de diagnóstico, não um prazo de resposta prometido pelo Google; se ele for atingido, o resultado no servidor continuará desconhecido.

umask 077
curl --silent --show-error \
  --connect-timeout 10 --max-time 90 \
  --request POST \
  'https://generativelanguage.googleapis.com/v1beta/interactions' \
  --header "x-goog-api-key: ${GEMINI_API_KEY:?Set GEMINI_API_KEY locally}" \
  --header 'Content-Type: application/json' \
  --data '{"model":"gemini-4-argon","input":"Reply with the word OK."}' \
  --dump-header argon-headers.txt \
  --output argon-response.json \
  --write-out 'HTTP %{http_code}; elapsed %{time_total}s\n'

Não há repetição automática neste comando, de propósito. Salve a resposta uma vez e depois classifique o resultado. O código de saída zero do curl significa apenas que a transferência foi concluída; confira o status HTTP e o corpo antes de considerar a chamada ao modelo bem-sucedida.

Se a requisição mínima funciona, mas sua aplicação falha, reintroduza um recurso por vez: estado da conversa, arquivos, ferramentas e, por último, configurações personalizadas de geração. Mantenha uma pequena tabela com o recurso adicionado e o status obtido. A primeira adição que falha reduz o campo da investigação; mudar chave, modelo, payload e SDK ao mesmo tempo elimina essa comparação.

Se ambas falham, use o mesmo corpo de erro para escolher o próximo caminho. Uma chamada bem-sucedida a outro modelo prova apenas que aquele modelo funcionou naquelas condições. Ela não comprova permissão para o Argon nem compatibilidade de recursos.

Relacione o erro à próxima verificação

Os códigos abaixo seguem a referência de erros da Interactions API. Outros protocolos podem usar nomes de campos diferentes; não aplique a esta resposta um parser de choices da OpenAI ou um parser antigo de candidates sem um adaptador.

Esses são caminhos de investigação, não garantias de que uma alteração específica resolverá todas as respostas. Um proxy, por exemplo, pode substituir o erro upstream; nesse caso, o 404 exibido não comprova que o Google rejeitou o ID do modelo.

Erros 400 e 404 após migrar de um cliente Gemini antigo

Anote o conjunto de parâmetros do protocolo: host, versão da API, endpoint, esquema do payload e parser da resposta. Compare o conjunto inteiro com a documentação do provedor. Alterar apenas o nome do modelo em um workflow antigo não constitui uma migração completa.

Na Interactions API do Google, o exemplo mínimo acima usa model e input. Não envie para esse endpoint um corpo compatível com OpenAI usando messages. O Google ainda oferece suporte à API original generateContent, mas os formatos de requisição e resposta são diferentes; a visão geral de Interactions e seus links de migração explicam essa distinção. Uma integração antiga que funciona não precisa ser reescrita só porque um artigo de diagnóstico usa um endpoint mais novo.

A especificação do Argon informa saída em texto. Compreender imagens e áudio não equivale a gerar imagens e áudio. Ela também informa cache implícito, em vez de explícito, e ausência de suporte à Live API. Se a requisição que falha depende de um desses recursos não suportados, use um modelo ou interface que documente essa capacidade; trocar o nome do modelo não adiciona o recurso.

Remova personalizações antigas de amostragem ao isolar erros de migração. Segundo o guia de solução de problemas do Google, o Gemini 4 ignora valores personalizados de temperature, top_p e top_k com avisos de descontinuação, e a rejeição está prevista para uma versão futura. Não afirme que essas configurações sempre causam um 400 hoje, nem dependa de aumentar a temperatura para corrigir a saída do Argon.

Critério de validação: a requisição mínima funciona, e o primeiro recurso que falhava passa a funcionar após uma correção documentada. Salve os dois payloads sem dados sensíveis. Se a requisição mínima ainda retorna 404, pare de adicionar recursos e resolva primeiro a incompatibilidade de rota, modelo ou recurso.

Erro 429: diferencie um pico de tráfego de uma cota esgotada

O Google aplica limites de taxa por projeto, não por chave. Portanto, uma segunda chave do mesmo projeto não cria uma nova reserva de cota. Confira no AI Studio os limites ativos para o projeto e modelo efetivamente usados: requisições por minuto, tokens de entrada por minuto, requisições por dia e qualquer limite aplicável baseado em gastos.

Analise os detalhes do erro junto com o histórico de uso. Um lote iniciado de repente pode ultrapassar um limite de curto prazo mesmo quando o uso diário é baixo. Uma cota diária esgotada não se resolve com outra tentativa alguns segundos depois. As cotas diárias de requisições são redefinidas à meia-noite do horário do Pacífico; esse não é um horário universal de redefinição para todo erro 429.

Para lidar com picos, primeiro reduza a concorrência e coloque as tarefas em uma fila. Se prompts grandes causam o problema, diminuir apenas o número de requisições pode não reduzir o consumo de tokens o suficiente. Quando a cota estiver esgotada, pause a tarefa até a redefinição correspondente ou uma mudança de capacidade autorizada, em vez de reenviá-la repetidamente.

Uma política prática de recuperação precisa de três controles:

• Um único componente é responsável pelas novas tentativas. Verifique o comportamento do SDK antes de envolvê-lo em outro loop de repetição.
• Falhas temporárias usam esperas crescentes com variação aleatória, um número máximo de tentativas e um tempo total máximo. Respeite o intervalo de espera informado pelo serviço, quando houver.
• Falhas persistentes de acesso, payload ou pagamento interrompem a execução e exibem uma mensagem útil. O tratamento de cota esgotada aguarda capacidade, em vez de consumir o orçamento de tentativas destinado a falhas temporárias.

Para uma pequena tarefa interativa, você pode definir no máximo três tentativas no total em dois minutos. Isso é um exemplo de política da aplicação, não uma cota do Google nem uma recomendação para toda carga de trabalho. Processamento em lote exige prazo e limite de gastos próprios. As orientações do Google sobre novas tentativas recomendam backoff limitado; elas não tornam as tentativas gratuitas nem garantem a conclusão.

HTTP 200 sem resposta: confira a conclusão e a saída

Trate o sucesso do transporte e o sucesso da tarefa como verificações distintas. No streaming, continue consumindo os eventos e trate eventos de erro; um status HTTP inicial de sucesso não comprova que o fluxo terminou. Na execução em segundo plano, salve o ID da interação e consulte essa mesma interação, em vez de criar uma tarefa idêntica a cada consulta de status.

O recurso Interactions registra etapas de execução, incluindo chamadas de ferramentas e saídas do modelo. No exemplo de início rápido do SDK, use o campo auxiliar documentado output_text. Se você interpreta o JSON bruto, siga o esquema daquele endpoint e versão. Inspecione todos os conteúdos relevantes da saída do modelo, em vez de presumir que a primeira entrada do array é a resposta final.

Quando o texto visível estiver vazio, siga esta ordem:

1. Ainda está em execução? Uma interação na fila ou em andamento não é uma resposta vazia concluída. Preserve o ID e confira o estado dentro do prazo da tarefa.
2. Está esperando uma ferramenta? Uma chamada de função válida é trabalho para sua aplicação, não necessariamente texto para o usuário. Valide os argumentos e conclua o fluxo previsto da ferramenta.
3. Foi bloqueada ou falhou? Preserve o motivo informado. Em caso de restrição de segurança, adapte a tarefa legítima ou explique a restrição; não a classifique como indisponibilidade nem tente contorná-la.
4. É um problema de orçamento ou interpretação da resposta? Confira uso, detalhes de conclusão e resposta bruta em relação ao que a interface exibiu. O orçamento de saída do Argon inclui raciocínio e saída visível, portanto um limite muito baixo definido sem análise pode prejudicar uma tarefa de raciocínio. Aumentá-lo também altera o custo potencial; investigue primeiro.

O guia do Argon documenta execução em segundo plano para gerações longas. Não copie uma configuração de longa duração para um teste curto de “OK”. Se o cliente atingiu o timeout depois de enviar uma tarefa real, o servidor pode continuar processando. Recupere a interação existente quando possível e avalie o risco de duplicação antes de iniciar uma substituta.

Critério de validação: sua aplicação distingue tarefas pendentes, ações de ferramentas, texto concluído e resultados com falha ou bloqueio. Ela não deve exibir todos esses estados como uma mensagem vazia de sucesso.

Teste o tratamento localmente antes de gastar com outra requisição

Este exercício sintético testa as decisões da aplicação sem alegar reproduzir a disponibilidade atual do Google. Passe estes casos pela interface e pelo tratamento de erros com as chamadas de rede desativadas:

Esses são cenários de teste, não fixtures completos de respostas da API. Monte os dados de teste conforme a versão do SDK e da API que você usa. Verifique se os logs excluem chaves e conteúdo privado dos prompts, e se uma única ação do usuário não dispara acidentalmente tanto uma nova tentativa quanto uma tarefa de fallback.

Quando trocar de modelo e o que enviar ao suporte

Um modelo alternativo só ajuda em uma tarefa urgente depois de você confirmar que ele suporta o tipo de entrada, as ferramentas, o esquema de saída e o tamanho de contexto necessários. Use uma pequena amostra de validação específica da tarefa, sinalize a troca de modelo e evite efeitos duplicados, como enviar a mesma mensagem duas vezes. Não encaminhe arquivos privados para outro provedor sem verificar os requisitos aplicáveis ao tratamento dos dados.

Para erros 5xx persistentes, consulte o status do serviço Google AI Studio. Um relato de usuário ou uma única requisição sua que falhou não comprova uma indisponibilidade em toda a plataforma. Se a requisição mínima continuar falhando, envie ao provedor um registro do incidente com dados sensíveis removidos:

Horário em UTC e fuso horário:
Provedor / host / endpoint / versão da API:
ID do modelo / versão do SDK:
Referência do projeto (somente em canal privado de suporte):
Status HTTP / código de erro / mensagem sem dados sensíveis:
Streaming ou execução em segundo plano ativados:
ID da interação, se disponível:
Tempo decorrido / total de tentativas:
Resultado da requisição mínima:
Primeiro recurso reintroduzido que falha:
Resultado esperado / resultado observado:

Consulte o guia de preços da API do Argon, em inglês antes de aumentar os orçamentos de saída ou executar testes repetidos. Para ajudar na escolha de modelo, veja o comparativo do Argon, em inglês. A Ofox publica este guia; a requisição direta ao Google mostrada acima não comprova que o Argon está disponível pela Ofox. Verifique o catálogo atual de modelos e o protocolo suportado pelo provedor antes de migrar o workflow.