Os erros do Gemini API parecem ter muitos nomes, mas na prática se encaixam em quatro grupos: identidade errada, endereço errado, cota insuficiente e rede inacessível. Problemas causados pelo próprio modelo são minoria.

Este artigo separa os erros por código e apresenta uma ordem de diagnóstico que começa pela requisição mínima. Ao encontrar um problema, salve primeiro o JSON completo do erro e depois verifique na ordem; não altere Key, endereço e modelo ao mesmo tempo.

Nota: Google e Gemini são marcas registradas de seus titulares. Este artigo usa a forma comum da interface em outubro de 2026 como exemplo; versões da interface, cotas e políticas regionais seguem a documentação oficial e a página de preços do site.

1. Aprenda primeiro a ler o corpo do erro

Os erros das APIs do Google normalmente retornam JSON com três campos-chave:

{
  "error": {
    "code": 429,
    "message": "Quota exceeded for quota metric ...",
    "status": "RESOURCE_EXHAUSTED"
  }
}

code é o status HTTP, status é o tipo de erro legível por máquina e message costuma conter a causa específica; details pode trazer o ID da cota e o horário sugerido para nova tentativa. No diagnóstico, leia os três: olhar apenas "429" esconde se é limite por minuto ou cota diária esgotada.

Status code status comum Direção geral
401 UNAUTHENTICATED Key ausente, inválida ou no lugar errado
403 PERMISSION_DENIED Projeto não ativado, permissão ou região restrita
404 NOT_FOUND Nome de modelo, caminho ou versão incorretos
429 RESOURCE_EXHAUSTED Taxa, concorrência ou cota excedidas
400 INVALID_ARGUMENT / FAILED_PRECONDITION Parâmetro errado, região não suportada, pré-condição não atendida
500/503 INTERNAL / UNAVAILABLE Falha temporária upstream; normalmente cabe backoff e retry

2. 401: Key inválida ou método de autenticação errado

O núcleo do 401 é "o servidor não reconhece sua identidade". Causas comuns:

  • A requisição não leva Key, ou a variável de ambiente está vazia.
  • A interface nativa usa Authorization em vez de x-goog-api-key.
  • A interface compatível com OpenAI usa x-goog-api-key em vez de Authorization: Bearer.
  • Há espaços ou quebras de linha antes ou depois da Key, ou aspas copiadas junto.
  • A Key foi excluída ou rotacionada, ou o projeto foi desativado.
  • A Key de gateway foi enviada ao endereço oficial do Google, ou o contrário.
  • A Key tem restrições de API que impedem chamadas ao Gemini API.

Confirme primeiro com uma requisição mínima:

export GEMINI_API_KEY="sua-chave"

# Interface nativa do Gemini
curl "https://generativelanguage.googleapis.com/v1beta/models/<ID-do-modelo>:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"Responda apenas OK"}]}]}'

# Interface compatível com OpenAI
curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
  -H "Authorization: Bearer $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<ID-do-modelo>","messages":[{"role":"user","content":"Responda apenas OK"}]}'

Os dois comandos correspondem a dois esquemas de autenticação. O que funcionar indica a qual sistema sua Key e seu endereço pertencem; um 401 ao misturar os dois não significa Key quebrada, mas combinação errada.

3. 404: nome de modelo, caminho ou versão incorretos

404 não significa necessariamente "o modelo não existe". Casos comuns:

  1. O ID do modelo está escrito errado, ou foi usado o nome de exibição do console em vez do identificador da API.
  2. O modelo não pertence à versão atual da API, por exemplo, um modelo liberado só na versão nova enviado a um caminho antigo.
  3. A Base URL tem /v1 ou /v1beta a mais ou a menos, e a montagem do caminho gera um endereço inexistente.
  4. Há uma barra extra no fim do endereço e o cliente monta o caminho mais uma vez.
  5. Ao chamar pelo gateway, o modelo não está liberado no grupo ou plano atual.
  6. Foi usada a interface de chat para chamar geração de imagens ou outra interface dedicada.

No diagnóstico, liste primeiro os modelos disponíveis para a Key atual:

curl "https://generativelanguage.googleapis.com/v1beta/models" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

Se o modelo desejado está na lista, confira o caminho da requisição; se não está, resolva primeiro a liberação ou a permissão. Ao chamar pelo gateway, use o ID de modelo e a Base URL indicados na documentação do gateway; não reutilize diretamente o nome oficial.

4. 429: distinga primeiro limitação de cota esgotada

429 é o erro mais sujeito a diagnóstico errado. Ele cobre ao menos três situações:

Tipo Característica típica Direção de tratamento
Limite por minuto Concorrência alta por pouco tempo, erros concentrados em segundos Reduzir concorrência, backoff e retry
Cota diária esgotada Volume do dia atingiu o teto e as falhas persistem Aguardar reset, ampliar cota ou trocar de solução
Cota de projeto Vários serviços no mesmo projeto disputam a cota Separar projetos, Keys e cotas

O campo details do erro normalmente informa o ID da cota e o horário sugerido de nova tentativa. Não reenvie imediatamente ao ver 429; a tempestade de retries piora a situação. Instale a dependência antes: pip install requests. Uma lógica de backoff utilizável:

import random
import time
import requests

def generate(prompt: str, retries: int = 4):
    url = "https://generativelanguage.googleapis.com/v1beta/models/<ID-do-modelo>:generateContent"
    headers = {
        "x-goog-api-key": "sua-chave",
        "Content-Type": "application/json",
    }
    for attempt in range(retries):
        resp = requests.post(
            url,
            headers=headers,
            json={"contents": [{"parts": [{"text": prompt}]}]},
            timeout=60,
        )
        if resp.status_code == 200:
            return resp.json()
        if resp.status_code not in (429, 500, 503):
            resp.raise_for_status()
        wait = min(2 ** attempt, 30) + random.random()
        time.sleep(wait)
    raise RuntimeError("Tentativas esgotadas")

Retry resolve apenas congestionamento temporário, não cota esgotada. Em produção, acrescente timeout, circuit breaker e modelo alternativo; caso contrário, um único 429 derruba toda a cadeia.

5. Restrição regional: por que a conexão direta na China falha

O Gemini API só é oferecido em parte dos países e regiões. Quando a saída da requisição está em região não suportada, as manifestações comuns são três:

  • Timeout de conexão ou falha no handshake TLS, geralmente caminho de rede inacessível.
  • Retorno 400 FAILED_PRECONDITION, com mensagem do tipo location is not supported.
  • Retorno 403 PERMISSION_DENIED, possivelmente ligado a projeto, cobrança ou permissão regional.

Há dois conceitos facilmente confundidos: região de registro da conta e região de saída da requisição. Mesmo que a conta seja válida, se o servidor está em região não suportada, a requisição ainda pode ser recusada; por outro lado, conseguir abrir a página com um proxy local não significa que a requisição da API usa o mesmo caminho.

Ordem sugerida de tratamento:

  1. Confirme se a requisição sai do computador local, de um contêiner ou de um servidor e identifique o IP de saída real.
  2. Verifique se a região de saída está na lista oficial de suporte.
  3. Confira a região escolhida no servidor de nuvem e, se necessário, mude para uma região suportada.
  4. Se o negócio está principalmente na China, avalie acesso por gateway em conformidade, unificando rede e cobrança.
  5. Não trate "trocar de IP" como solução única; confirme antes os termos de serviço e a legislação local.

6. Outros erros frequentes

Sintoma Causa comum Tratamento
400 INVALID_ARGUMENT Estrutura JSON errada, ordem de papéis incorreta, formato de imagem não suportado Adicionar campos gradualmente com requisição mínima
400 FAILED_PRECONDITION Região não suportada, cobrança não ativada, pré-condição ausente Verificar região, cobrança e estado do projeto
403 PERMISSION_DENIED API não ativada, restrição de Key, permissão de projeto insuficiente Ativar no console e conferir permissões
500 INTERNAL Erro interno upstream Backoff e retry, registrar request ID
503 UNAVAILABLE Sobrecarga ou manutenção upstream Backoff e retry, trocar para modelo alternativo
Resposta sem conteúdo Bloqueio de política de segurança, saída truncada Ver blockReason e finishReason
Saída interrompida no meio Limite máximo de tokens de saída atingido Aumentar o limite ou encurtar a entrada

"Resposta sem conteúdo" é frequentemente tratado como falha, mas na verdade é filtro de segurança ou limite de tamanho. Verifique promptFeedback.blockReason, finishReason e usageMetadata na resposta e só então decida entre alterar o prompt ou ajustar parâmetros.

7. Ordem de diagnóstico recomendada

  1. Salve o JSON completo do erro, o horário da requisição, o ID do modelo e o request ID.
  2. Envie uma requisição mínima com curl para eliminar interferência do cliente e do SDK.
  3. Confira três itens: Base URL, cabeçalho de autenticação e ID do modelo.
  4. Troque para um modelo sabidamente disponível e veja se o problema é do modelo ou da cadeia.
  5. Consulte cota, cobrança e estado do projeto para distinguir 429 de 403.
  6. Confirme a região de saída da requisição e o caminho de rede.
  7. Por último, revise configuração do cliente, proxy e lógica de retry no código.

Altere uma variável por vez. Caso contrário, mesmo que o serviço volte, você não saberá qual passo resolveu e repetirá o erro na próxima vez.

8. Perguntas frequentes

Qual é a diferença entre 401 e 403?

401 é "identidade não validada": verifique primeiro Key, cabeçalho de autenticação e compatibilidade de endereço. 403 é "identidade válida, mas sem permissão": verifique se a API está ativada, permissões do projeto, restrições da Key e política regional.

Basta esperar alguns minutos após um 429?

Depende do tipo de cota. Limite por minuto normalmente se recupera após backoff; cota diária esgotada exige esperar o reset ou ampliar a cota. Leia o ID de cota e a sugestão de retry no corpo do erro; não reenvie às cegas.

Trocar de IP resolve a restrição regional?

Não necessariamente. Depende da região real de saída, do estado da conta e dos termos de serviço. No contexto empresarial, é mais seguro implantar em região suportada ou acessar por um gateway em conformidade.

O endereço oficial funciona, mas o gateway retorna 404. De quem é o problema?

Confira primeiro a Base URL e o ID de modelo do gateway. A nomenclatura, o caminho e o escopo do gateway podem diferir do oficial; não reutilize diretamente a requisição oficial. Substitua item a item pelo exemplo mínimo da documentação do gateway.

Como evitar que retries multipliquem o custo?

Defina número máximo de retries, backoff exponencial e timeout; trate 429 separadamente; adicione deduplicação a requisições não idempotentes; e configure teto de orçamento e alertas no gateway.

Próximos passos

A chave do diagnóstico de erros do Gemini é separar primeiro as quatro categorias — autenticação, caminho, cota e rede — e verificar item a item com uma requisição mínima. Se você precisa de entrada unificada e menos incerteza na conexão direta na China, registre-se no ZSQH AI Gateway; modelos, cotas e preços seguem a página de preços.

Leitura relacionada: