Erros da API

Esta página fornece uma referência para códigos de erro de back-end retornados pela API GenerateContent, descreve o formato de resposta de erro do gRPC e fornece etapas de solução de problemas.

Códigos de erro HTTP

A tabela a seguir lista códigos de erro comuns de back-end, explicações sobre as causas e soluções recomendadas:

Código HTTP Status Descrição Exemplo Solução
400 INVALID_ARGUMENT O corpo da solicitação está malformado. Há um erro de digitação ou um campo obrigatório ausente na solicitação. Consulte a referência da API para ver o formato da solicitação, exemplos e versões compatíveis. O uso de recursos de uma versão mais recente da API com um endpoint mais antigo pode causar erros.
400 FAILED_PRECONDITION O nível sem custo financeiro da API Gemini não está disponível no seu país. Ative o faturamento no seu projeto no Google AI Studio. Você está fazendo uma solicitação em uma região em que o nível sem custo financeiro não é aceito e não ativou o faturamento no seu projeto no Google AI Studio. Para usar a API Gemini, configure um plano pago usando Google AI Studio.
403 PERMISSION_DENIED Sua chave de API não tem as permissões necessárias. Você está usando a chave de API errada ou tentando usar um modelo ajustado sem passar pela autenticação adequada. Verifique se a chave de API está definida e tem o acesso correto. E faça a autenticação adequada para usar modelos ajustados.
404 NOT_FOUND O recurso solicitado não foi encontrado. Um arquivo de imagem, áudio ou vídeo referenciado na solicitação não foi encontrado. Verifique se todos os parâmetros na solicitação são válidos para a versão da API.
429 RESOURCE_EXHAUSTED Você excedeu um dos limites de taxa da API (RPM, TPM, RPD, gastos etc.). Você está enviando muitas solicitações, usando muitos tokens ou excedendo os limites baseados em gastos para o histórico de faturamento e o nível da sua conta. Verifique se você está dentro dos limites de taxa do modelo. Aguarde e tente novamente após um breve período. Reduza a taxa ou o tamanho das solicitações. Solicite um aumento no limite de taxa, se necessário.
499 CANCELADO A operação foi cancelada, geralmente pelo autor da chamada. O cliente fechou a conexão antes que a API pudesse terminar de responder. Verifique se o cliente ou a infraestrutura de rede está fechando a conexão prematuramente (por exemplo, devido a um tempo limite do lado do cliente).
500 INTERNAL Ocorreu um erro inesperado no Google. O contexto de entrada é muito longo. Confira a página de status da API Gemini para ver se há incidentes em andamento. Reduza o contexto de entrada ou mude temporariamente para outro modelo (por exemplo, do Gemini 2.5 Pro para o Gemini 2.5 Flash) e veja se funciona. Ou aguarde um pouco e tente fazer a solicitação novamente. Se o problema persistir após a nova tentativa, informe-o usando o botão Enviar feedback no Google AI Studio.
503 INDISPONÍVEL O serviço pode estar temporariamente sobrecarregado ou inativo. O serviço está temporariamente sem capacidade. Confira a página de status da API Gemini para ver se há incidentes em andamento. Mude temporariamente para outro modelo (por exemplo, do Gemini 2.5 Pro para o Gemini 2.5 Flash) e veja se funciona. Ou aguarde um pouco e tente fazer a solicitação novamente. Se o problema persistir após a nova tentativa, informe-o usando o botão Enviar feedback no Google AI Studio.
504 DEADLINE_EXCEEDED O serviço não consegue concluir o processamento dentro do prazo. Seu comando (ou contexto) é muito grande para ser processado a tempo. Defina um "tempo limite" maior na solicitação do cliente para evitar esse erro.

Formato de resposta de erro

Quando uma solicitação GenerateContent falha, a API define o código de status HTTP (como 400 Bad Request, 403 Forbidden ou 429 Too Many Requests) e retorna um corpo de resposta JSON contendo detalhes de status do gRPC:

{
  "error": {
    "code": 400,
    "message": "API key not valid. Please pass a valid API key.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "API_KEY_INVALID",
        "domain": "googleapis.com",
        "metadata": {
          "service": "generativelanguage.googleapis.com"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
        "locale": "en-US",
        "message": "API key not valid. Please pass a valid API key."
      }
    ]
  }
}
Campo Tipo Descrição
code número inteiro O código de status HTTP.
message string Uma descrição do erro legível por humanos.
status string O código de status do gRPC em SCREAMING_CASE.
details matriz Contexto de erro adicional, como ErrorInfo ou LocalizedMessage.

A seguir