Nesta página, mostramos como resolver problemas de códigos de erro comuns dos SDKs do Gemini API e do Firebase AI Logic.
Erro 400: API key not valid. Please pass a valid API key.
Se você receber um erro 400 que diz
API key not valid. Please pass a valid API key., isso geralmente significa que a
chave de API no seu arquivo/objeto de configuração do Firebase não existe ou não está configurada
para ser usada com seu app e/ou projeto do Firebase.
Verifique se a chave de API listada no arquivo/objeto de configuração do Firebase corresponde à chave de API do seu app. É possível conferir todas as chaves de API no painel APIs e serviços > Credenciais no console do Google Cloud.
Se você descobrir que eles não correspondem, consiga um novo objeto/arquivo de configuração do Firebase e substitua o que está no seu app. O novo objeto/arquivo de configuração precisa conter uma chave de API válida para seu app e projeto do Firebase.
Erro 400: Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.
Se você estiver tentando enviar uma solicitação multimodal com um URL do Cloud Storage for Firebase,
talvez encontre o seguinte erro 400:
Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.
Esse erro é causado por um projeto que não teve os agentes de serviço necessários provisionados automaticamente de maneira correta quando a API Agent Platform foi ativada no projeto. Esse é um problema conhecido em alguns projetos, e estamos trabalhando em uma correção global.
Veja como corrigir seu projeto e provisionar corretamente esses agentes de serviço para que você possa começar a incluir URLs do Cloud Storage for Firebase nas suas solicitações multimodais. Você precisa ser um proprietário do projeto e só precisa concluir esse conjunto de tarefas uma vez.
Acesse e autentique com o gcloud CLI.
A maneira mais fácil de fazer isso é no Cloud Shell. Saiba mais na documentação do Google Cloud.Se solicitado, siga as instruções exibidas no terminal para que o gcloud CLI seja executado no seu projeto do Firebase.
Você vai precisar do ID do projeto do Firebase, que pode ser encontrado na parte de cima das settings Configurações do projeto no console do Firebase.
Provisione os agentes de serviço necessários no projeto executando o seguinte comando:
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/endpoints -d ''
Aguarde alguns minutos para garantir que os agentes de serviço sejam provisionados e, em seguida, tente enviar novamente a solicitação multimodal que inclui o URL do Cloud Storage for Firebase.
Se o erro persistir após alguns minutos, entre em contato com o suporte do Firebase.
Erro 403: PERMISSION_DENIED: To access this model, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check
Se você receber um erro 403 - PERMISSION_DENIED que diz
To access this model, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check,
significa que sua solicitação não tem um token App Check válido e você está
tentando acessar um modelo que costuma ser usado de forma indevida.
Alguns modelos generativos foram identificados como comuns para abuso por usuários maliciosos.
Como você não tem App Check aplicado para Firebase AI Logic, seu projeto está vulnerável ao abuso desses modelos. Para proteger nossos desenvolvedores, o Firebase bloqueia o acesso a esses modelos, a menos que a solicitação inclua um token App Check válido (o que significa que o App Check é aplicado para Firebase AI Logic).
Se você quiser acessar o modelo que retornou o erro, faça o seguinte:
Configurar o App Check para o Firebase AI Logic. Para o desenvolvimento local, configure o App Check provedor de depuração.
Aplicar o App Check é essencial para proteger os modelos Gemini API e Gemini contra abusos, e a aplicação é necessária para resolver esse erro.
Reenvie a solicitação do seu app para Firebase AI Logic.
Essa solicitação vai enviar um token App Check válido, e você não vai mais receber o erro
403 - PERMISSION_DENIED.Antes de lançar o app para os usuários finais, é necessário configurar um provedor de atestado de produção (como o App Attest, o Play Integrity ou o reCAPTCHA Enterprise) para que os usuários finais possam acessar o recurso de IA quando o App Check for aplicado.
Erro 403: PERMISSION_DENIED: Firebase AI Logic has been deactivated in this project. To resume using Firebase AI Logic, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check
Se você receber um erro 403 - PERMISSION_DENIED que diz
Firebase AI Logic has been deactivated in this project. To resume using
Firebase AI Logic, you must enforce Firebase App Check. Learn more:
https://firebase.google.com/docs/ai-logic/app-check,
significa que seu projeto do Firebase foi identificado como inativo e você
não tem App Check aplicado para Firebase AI Logic.
"Projetos inativos" são aqueles que têm o Firebase AI Logic ativado, mas não têm uso recente do Firebase AI Logic.
Como você não tem App Check aplicado para Firebase AI Logic, seu projeto está vulnerável ao abuso de Gemini API. Para proteger seu projeto, o Firebase desativou o uso de Firebase AI Logic até que você aplique App Check para Firebase AI Logic.
Quando estiver tudo pronto para começar a usar o Firebase AI Logic novamente, faça o seguinte:
Configurar o App Check para o Firebase AI Logic. Para o desenvolvimento local, configure o App Check provedor de depuração.
Aplicar o App Check é essencial para proteger os modelos Gemini API e Gemini contra abusos, e a aplicação é necessária para resolver esse erro.
Reenvie a solicitação do seu app para Firebase AI Logic.
Essa solicitação vai enviar um token App Check válido, e você não vai mais receber o erro
403 - PERMISSION_DENIED.Se você já aplica App Check e ainda recebe esse erro, verifique se a proteção contra repetição está ativada para Firebase AI Logic (inclusive no modo "Somente monitoramento").
Quando a proteção contra repetição está ativada, apenas os tokens de uso limitado contam como verificados para Firebase AI Logic. Os tokens de sessão regulares não eliminam esse erro. Ative os tokens de uso limitado no app ou desative a proteção contra repetição para Firebase AI Logic, reenvie uma solicitação e aguarde cerca de um dia antes de reativar a proteção contra repetição (a atividade do projeto é reavaliada diariamente).
Antes de lançar o app para os usuários finais, é necessário configurar um provedor de atestado de produção (como o App Attest, o Play Integrity ou o reCAPTCHA Enterprise) para que os usuários finais possam acessar o recurso de IA quando o App Check for aplicado.
Erro 403: PERMISSION_DENIED: The caller does not have permission.
Se você receber um erro 403 que diz
PERMISSION_DENIED: The caller does not have permission., isso geralmente significa que
a chave de API no arquivo/objeto de configuração do Firebase pertence a um projeto
diferente.
Verifique se a chave de API listada no arquivo/objeto de configuração do Firebase corresponde à chave de API do seu app. É possível conferir todas as chaves de API no painel APIs e serviços > Credenciais no console do Google Cloud.
Se você descobrir que eles não correspondem, consiga um novo objeto/arquivo de configuração do Firebase e substitua o que está no seu app. O novo objeto/arquivo de configuração precisa conter uma chave de API válida para seu app e projeto do Firebase.
Erro 403: Requests to this API firebasevertexai.googleapis.com ... are blocked.
Se você receber um erro 403 que diz
Requests to this API firebasevertexai.googleapis.com ... are blocked., isso
geralmente significa que a chave de API na configuração do Firebase no seu app tem
restrições que impedem que ela chame a API necessária.
Para corrigir isso, atualize as restrições da chave de API no console do Google Cloud para incluir a API necessária. Para Firebase AI Logic,
verifique se a API Firebase AI Logic
(firebasevertexai.googleapis.com) está incluída na lista de APIs
selecionadas que podem ser chamadas usando a chave de API.
Siga estas etapas:
No console do Google Cloud, abra o painel APIs e serviços > Credenciais.
Selecione a chave de API que seu aplicativo está configurado para usar (por exemplo, a "chave do iOS" para um app iOS).
Na página Editar chave de API, encontre a seção Restrições de API.
Verifique se a opção Restringir chave está selecionada. Se não estiver, sua chave não tem restrições, e essa provavelmente não é a origem do erro.
No menu suspenso APIs selecionadas, pesquise e selecione a API Firebase AI Logic para adicioná-la à lista de APIs selecionadas que podem ser chamadas usando a chave de API.
Clique em Salvar.
Pode levar até cinco minutos para que as mudanças entrem em vigor.
Erro 404: Firebase AI Logic genai config not found
Se você receber um erro 404 que diz Firebase AI Logic genai config not found,
isso geralmente significa que uma configuração para Firebase AI Logic está incorreta ou
ausente.
Estas são as causas mais prováveis desse erro:
Você ainda não configurou seu projeto do Firebase para um provedor do Gemini API.
O que fazer:
No console do Firebase, acesse Serviços de IA > Lógica de IA. Clique em Começar e selecione o provedor de Gemini API escolhido. Ative a API, e o Firebase vai configurar seu projeto para esse provedor. Depois de concluir o fluxo de trabalho, tente fazer a solicitação novamente.Se você tiver passado recentemente pelo fluxo de trabalho de configuração do Firebase AI Logic no console do Firebase, talvez a configuração do Firebase AI Logic ainda não esteja disponível para todos os serviços de back-end necessários em todas as regiões aplicáveis.
O que fazer:
Aguarde alguns minutos e tente fazer a solicitação novamente.
Erro 404: o modelo "was not found or your project does not have access to it"?
Por exemplo: "Publisher Model projects/PROJECT-ID/locations/us-central1/publishers/google/models/gemini-3.1-pro-preview was not found or your project does not have access to it. Please ensure you are using a valid model version."
Há alguns motivos para você receber um erro como esse.
Nome do modelo inválido
Causa: o nome do modelo fornecido não é válido.
Correção: verifique o nome e a versão do modelo na lista de todos os modelos compatíveis e disponíveis. Verifique os segmentos e a ordem deles no nome do modelo. Exemplo:
- Nome do modelo
Gemini 4 Argon mais recente:
gemini-4-argon - Nome do modelo Gemini 3.x Pro
mais recente:
gemini-3.1-pro-preview(disponível apenas em pré-lançamento) - Nome do modelo
Gemini 3.x Flash mais recente:
gemini-3.8-flash - Nome do modelo
Gemini 3.x Flash‑Lite mais recente:
gemini-3.5-flash-lite - Nome do modelo
Gemini Nano Banana 2.1 mais recente:
gemini-nano-banana-2.1 - Nome do modelo
Gemini Nano Banana 2 mais recente:
gemini-3.1-flash-image - Nome do modelo
Gemini Nano Banana 2 Lite mais recente:
gemini-3.1-flash-lite-image - Nome do modelo
Gemini Nano Banana Pro mais recente:
gemini-3-pro-image
- Nome do modelo
Gemini 4 Argon mais recente:
Local inválido (aplicável apenas se você estiver usando o provedor Agent Platform Gemini API (formerly Vertex AI))
Causa: sua solicitação pode estar tentando acessar um modelo em um local em que ele não está disponível.
Correção: verifique se a solicitação está tentando acessar o modelo onde ele está disponível.
Ao usar o Agent Platform Gemini API (formerly Vertex AI), é possível especificar um local para acessar o modelo durante a inicialização. Se você não especificar um local, Firebase AI Logic vai usar os seguintes locais como padrão:
- Ao usar a sintaxe de inicialização da "Agent Platform":
global - Ao usar a sintaxe de inicialização legada "Vertex AI":
us-central1
No entanto, nem todos os modelos são compatíveis com esses locais padrão. Isso significa que, dependendo do modelo, pode ser necessário definir explicitamente um local específico durante a inicialização.
Modelos Gemini experimentais e de pré-lançamento: disponíveis apenas no local
global.Modelos estáveis Gemini 4.x e Gemini 3.x: disponíveis no local
globale, geralmente, nos locaisuseeu.Modelos Gemini 2.5:disponíveis em vários locais. Os modelos Gemini Live API 2.5 não estão disponíveis no
global.
- Ao usar a sintaxe de inicialização da "Agent Platform":
Saiba como especificar o local para acessar o modelo (incluindo snippets de código).
Erros 429: "You exceeded your current quota, please check your plan and billing details" ou "Resource exhausted, please try again later."
Há alguns motivos para você receber um erro como esse.
Você está ultrapassando sua cota ou o modelo que está acessando está sobrecarregado com solicitações de outras pessoas.
A ação a ser tomada depende se você está usando o Gemini Developer API ou o Agent Platform Gemini API (formerly Vertex AI). Para mais informações sobre cotas e como solicitar mais, consulte Limites de taxa e cotas.
Se você estiver usando o Agent Platform Gemini API (formerly Vertex AI), a documentação do Google Cloud fornece mais contexto e orientações para o Código do erro 429.
Você está tentando usar um modelo ou um recurso que exige faturamento, mas seu projeto do Firebase está no plano de preços Spark.
Se você estiver usando o Gemini Developer API, poderá ter acesso limitado a determinados modelos e acesso a muitos recursos básicos no "nível sem custo financeiro" do Gemini Developer API. Esse nível permite que você comece sem precisar fornecer uma forma de pagamento, o que significa que não é necessário fazer upgrade do projeto do Firebase para o plano de preços Blaze de pagamento por uso.
Alguns modelos não estão disponíveis no nível sem custo financeiro do Gemini Developer API e exigem o nível pago, o que significa que seu projeto precisa estar no plano de preços Blaze de pagamento por uso. Por exemplo, os seguintes modelos quase sempre exigem faturamento:
- A maioria dos modelos de pré-lançamento e experimentais
- Modelos de geração de mídia (como os modelos Gemini Nano Banana)
Alguns modelos oferecem recursos básicos no Gemini Developer API "nível sem custo financeiro", mas exigem o "nível pago" para usar recursos avançados. Exemplo:
- Ao usar a maioria dos modelos Gemini 3.x,
o embasamento com
Google Search ouGoogle Maps exige faturamento.
- Ao usar a maioria dos modelos Gemini 3.x,
o embasamento com
Saiba mais sobre os planos de preços do Firebase e o Gemini Developer API.
Para mais detalhes, consulte a Gemini Developer API documentação de preços e as perguntas frequentes sobre faturamento.