Codici di errore

Errore 400: API key not valid. Please pass a valid API key.

Se ricevi un errore 400 che indica API key not valid. Please pass a valid API key., in genere significa che la chiave API nel file/oggetto di configurazione Firebase non esiste o non è configurata per essere utilizzata con la tua app e/o il tuo progetto Firebase.

Verifica che la chiave API elencata nel file/oggetto di configurazione di Firebase corrisponda alla chiave API della tua app. Puoi visualizzare tutte le tue chiavi API nel pannello API e servizi > Credenziali nella console Google Cloud.

Se scopri che non corrispondono, ottieni un nuovo file/oggetto di configurazione Firebase e poi sostituisci quello presente nella tua app. Il nuovo file/oggetto di configurazione deve contenere una chiave API valida per la tua app e il tuo progetto Firebase.

Errore 400: Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.

Se stai tentando di inviare una richiesta multimodale con un URL Cloud Storage for Firebase, potresti riscontrare il seguente errore 400:
Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.

Questo errore è causato da un progetto in cui non è stato eseguito il provisioning automatico corretto degli agenti di servizio richiesti quando l'API Agent Platform è stata abilitata nel progetto. Si tratta di un problema noto di alcuni progetti e stiamo lavorando a una correzione globale.

Ecco la soluzione alternativa per correggere il tuo progetto e eseguire il provisioning corretto di questi service agent in modo da poter iniziare a includere URL Cloud Storage for Firebase nelle tue richieste multimodali. Devi essere un proprietario del progetto e devi completare questo insieme di attività una sola volta per il progetto.

1. Accedere e autenticarsi con gcloud CLI.
   Il modo più semplice per farlo è da Cloud Shell. Scopri di più nella documentazione di Google Cloud.

2. Se richiesto, segui le istruzioni visualizzate nel terminale per eseguire gcloud CLI sul tuo progetto Firebase.

   Avrai bisogno dell'ID progetto Firebase, che puoi trovare nella parte superiore della pagina settings Impostazioni progetto nella console Firebase.

3. Esegui il provisioning dei service agent richiesti nel tuo progetto eseguendo questo 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 ''
   

4. Attendi qualche minuto per assicurarti che gli agenti di servizio siano sottoposti a provisioning, quindi riprova a inviare la richiesta multimodale che include l'URL Cloud Storage for Firebase.

Se continui a visualizzare questo errore dopo aver atteso diversi minuti, contatta l'assistenza Firebase.

Errore 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 ricevi un errore 403 - PERMISSION_DENIED che indica To access this model, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check, significa che la tua richiesta non ha un token App Check valido e stai tentando di accedere a un modello di cui viene comunemente eseguito un abuso.

Alcuni modelli generativi sono stati identificati come comunemente abusati da autori di attacchi informatici.

Poiché non hai applicato App Check per Firebase AI Logic, il tuo progetto è vulnerabile all'abuso di questi modelli. Per contribuire a proteggere i nostri sviluppatori, Firebase blocca l'accesso a questi modelli a meno che la richiesta non includa un token App Check valido (il che significa che App Check è applicato per Firebase AI Logic).

Se vuoi accedere al modello che ha restituito l'errore:

1. Configura App Check per Firebase AI Logic. Per lo sviluppo locale, assicurati di configurare il App Check provider di debug.

   L'applicazione di App Check è fondamentale per proteggere i modelli Gemini API e Gemini da comportamenti illeciti e la sua applicazione è necessaria per risolvere questo errore.

2. Invia di nuovo la richiesta dalla tua app a Firebase AI Logic.

   Questa richiesta invierà un token App Check valido e non riceverai più questo errore 403 - PERMISSION_DENIED.

3. Prima di rilasciare l'app agli utenti finali, devi configurare un fornitore di attestazione di produzione (come App Attest, Play Integrity o reCAPTCHA Enterprise) in modo che gli utenti finali possano accedere alla tua funzionalità di AI quando viene applicato App Check.

Errore 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 ricevi l'errore 403 - PERMISSION_DENIED che indica 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 che il tuo progetto Firebase è stato identificato come inattivo e non hai App Check applicato per Firebase AI Logic.

I "progetti inattivi" sono quelli per cui è attivato Firebase AI Logic, ma non è stato registrato alcun utilizzo recente di Firebase AI Logic.

Poiché non hai applicato App Check per Firebase AI Logic, il tuo progetto è vulnerabile all'abuso di Gemini API. Per contribuire a proteggere il tuo progetto, Firebase ha disattivato l'utilizzo di Firebase AI Logic finché non applichi App Check per Firebase AI Logic.

Quando vuoi ricominciare a usare Firebase AI Logic, procedi nel seguente modo:

1. Configura App Check per Firebase AI Logic. Per lo sviluppo locale, assicurati di configurare il App Check provider di debug.

   L'applicazione di App Check è fondamentale per proteggere i modelli Gemini API e Gemini da comportamenti illeciti e la sua applicazione è necessaria per risolvere questo errore.

2. Invia di nuovo la richiesta dalla tua app a Firebase AI Logic.

   Questa richiesta invierà un token App Check valido e non riceverai più questo errore 403 - PERMISSION_DENIED.

3. Se applichi già App Check e continui a ricevere questo errore, controlla se la protezione contro gli attacchi di riproduzione è attivata per Firebase AI Logic (anche in modalità "Solo monitoraggio").

   Quando la protezione di riproduzione è attiva, solo i token a uso limitato vengono conteggiati come verificati per Firebase AI Logic; i token di sessione regolari non risolvono questo errore. Attiva i token di utilizzo limitato nella tua app oppure disattiva la protezione dalla riproduzione per Firebase AI Logic, invia di nuovo una richiesta e attendi circa un giorno prima di riattivare la protezione dalla riproduzione (l'attività del progetto viene rivalutata ogni giorno).

4. Prima di rilasciare l'app agli utenti finali, devi configurare un fornitore di attestazione di produzione (come App Attest, Play Integrity o reCAPTCHA Enterprise) in modo che gli utenti finali possano accedere alla tua funzionalità di AI quando viene applicato App Check.

Errore 403: PERMISSION_DENIED: The caller does not have permission.

Se ricevi un errore 403 che indica PERMISSION_DENIED: The caller does not have permission., in genere significa che la chiave API nel file/oggetto di configurazione Firebase appartiene a un progetto Firebase diverso.

Verifica che la chiave API elencata nel file/oggetto di configurazione di Firebase corrisponda alla chiave API della tua app. Puoi visualizzare tutte le tue chiavi API nel pannello API e servizi > Credenziali nella console Google Cloud.

Se scopri che non corrispondono, ottieni un nuovo file/oggetto di configurazione Firebase e poi sostituisci quello presente nella tua app. Il nuovo file/oggetto di configurazione deve contenere una chiave API valida per la tua app e il tuo progetto Firebase.

Errore 403: Requests to this API firebasevertexai.googleapis.com ... are blocked.

Se ricevi un errore 403 che indica Requests to this API firebasevertexai.googleapis.com ... are blocked., di solito significa che la chiave API nella configurazione Firebase della tua app ha limitazioni che impediscono di chiamare l'API richiesta.

Per risolvere il problema, devi aggiornare le limitazioni della chiave API nella console Google Cloud in modo da includere l'API richiesta. Per Firebase AI Logic, devi assicurarti che l'API Firebase AI Logic (firebasevertexai.googleapis.com) sia inclusa nell'elenco delle API selezionate che possono essere chiamate utilizzando la chiave API.

Segui questi passaggi:

1. Nella console Google Cloud, apri il riquadro API e servizi > Credenziali.

2. Seleziona la chiave API che la tua applicazione è configurata per utilizzare (ad esempio, la "chiave iOS" per un'app per iOS).

3. Nella pagina Modifica chiave API, individua la sezione Restrizioni delle API.

4. Assicurati che l'opzione Limita chiave sia selezionata. In caso contrario, la chiave è senza restrizioni e probabilmente non è la causa dell'errore.

5. Nel menu a discesa API selezionate, cerca e seleziona l'API Firebase AI Logic per aggiungerla all'elenco delle API selezionate che possono essere chiamate utilizzando la chiave API.

6. Fai clic su Salva.

   Potrebbero essere necessari fino a cinque minuti prima che le modifiche abbiano effetto.

Errore 404: Firebase AI Logic genai config not found

Se ricevi un errore 404 che indica Firebase AI Logic genai config not found, di solito significa che un'impostazione per Firebase AI Logic è configurata in modo errato o mancante.

Ecco le cause più probabili di questo errore:

• Non hai ancora configurato il tuo progetto Firebase per un provider Gemini API.

  Cosa fare:
  Nella console Firebase, vai a Servizi AI > AI Logic. Fai clic su Inizia e poi seleziona il provider Gemini API che hai scelto. Abilita l'API e Firebase configurerà il tuo progetto per il provider. Dopo aver completato il flusso di lavoro, riprova a inviare la richiesta.

• Se hai completato di recente il flusso di lavoro di configurazione di Firebase AI Logic nella console Firebase, la configurazione di Firebase AI Logic potrebbe non essere ancora disponibile per tutti i servizi di backend richiesti in tutte le regioni applicabili.

  Cosa fare:
  Attendi qualche minuto e riprova a inviare la richiesta.

Errore 404: il modello "was not found or your project does not have access to it"?

Ad esempio: "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."

Esistono diversi motivi per cui potresti visualizzare un errore di questo tipo.

• Nome modello non valido

  • Causa: il nome del modello che hai fornito non è valido.

  • Correzione: controlla il nome e la versione del modello rispetto all'elenco di tutti i modelli supportati e disponibili. Assicurati di controllare i segmenti e il loro ordine nel nome del modello. Ad esempio:

    • Ultimo modello Gemini 3.x Pro Nome: gemini-3.1-pro-preview (disponibile solo in anteprima)
    • Ultimo modello Gemini 3.x Flash nome: gemini-3.8-flash
    • Ultimo modello Gemini 3.x Flash‑Lite nome: gemini-3.5-flash-lite
    • Nome del modello Gemini 3.x Pro Image più recente (noto anche come "Nano Banana Pro"): gemini-3-pro-image
    • Ultimo Gemini 3.x Flash Image (noto anche come "Nano Banana 2") Nome modello: gemini-3.1-flash-image
    • Ultimo Gemini 3.x Flash‑Lite Image (noto anche come "Nano Banana 2 Lite") Nome modello: gemini-3.1-flash-lite-image
    • Ultimo Gemini 2.5 Flash Image (noto anche come "Nano Banana") Nome modello: gemini-2.5-flash-image

• Località non valida (valido solo se utilizzi il fornitore Agent Platform Gemini API (formerly Vertex AI))

  • Causa: la tua richiesta potrebbe tentare di accedere a un modello in una località in cui non è disponibile.

  • Correzione: assicurati che la richiesta tenti di accedere al modello in cui è disponibile.

    Quando utilizzi Agent Platform Gemini API (formerly Vertex AI), puoi specificare facoltativamente una posizione per accedere al modello durante l'inizializzazione. Se non specifichi una posizione, Firebase AI Logic utilizza per impostazione predefinita le seguenti posizioni:

    • Quando utilizzi la sintassi di inizializzazione "Agent Platform": global
    • Quando utilizzi la sintassi di inizializzazione precedente "Vertex AI": us-central1

    Tuttavia, non tutti i modelli sono supportati in queste posizioni predefinite. Ciò significa che, a seconda del modello, potrebbe essere necessario impostare esplicitamente una posizione specifica durante l'inizializzazione.

    • Modelli anteprima e sperimentali Gemini: disponibili solo nella posizione global.

    • Modelli stabiliGemini 3.x: disponibili nella località global e spesso nelle località us e eu.

    • Modelli Gemini 2.5: Disponibili in molte località. Tieni presente che i modelli Gemini Live API 2.5 non sono disponibili in global.

  Scopri di più su come specificare la posizione per accedere al modello (inclusi gli snippet di codice).

Errori 429: "You exceeded your current quota, please check your plan and billing details" o "Resource exhausted, please try again later."

Esistono diversi motivi per cui potresti visualizzare un errore di questo tipo.

• Stai superando la quota o il modello a cui stai accedendo è sovraccarico di richieste di altre persone.

  L'azione da intraprendere dipende dal fatto che tu stia utilizzando Gemini Developer API o Agent Platform Gemini API (formerly Vertex AI). Per ulteriori informazioni sulle quote e su come richiedere quote aggiuntive, consulta Limiti di frequenza e quote.

  Se utilizzi Agent Platform Gemini API (formerly Vertex AI), la documentazione di Google Cloud fornisce ulteriore contesto e indicazioni per l'errore 429.

• Stai tentando di utilizzare un modello o una funzionalità che richiede la fatturazione, ma il tuo progetto Firebase è incluso nel piano tariffario Spark.

  Se utilizzi Gemini Developer API, puoi ottenere un accesso limitato a determinati modelli e accedere a molte funzionalità di base mentre utilizzi il "livello senza costi" di Gemini Developer API. Questo livello ti consente di iniziare senza dover fornire un metodo di pagamento, il che significa che non devi eseguire l'upgrade del tuo progetto Firebase al piano tariffario Blaze con pagamento a consumo.

  • Alcuni modelli non sono disponibili nel "livello senza costi" di Gemini Developer API e richiedono il "livello a pagamento", il che significa che il tuo progetto deve utilizzare il piano tariffario Blaze con pagamento a consumo. Ad esempio, i seguenti modelli richiedono quasi sempre la fatturazione:

    • La maggior parte dei modelli di anteprima e sperimentali
    • Modelli di generazione di immagini (i modelli "Nano Banana")

  • Alcuni modelli offrono alcune funzionalità di base nel Gemini Developer API "livello senza costi", ma poi richiedono il "livello a pagamento" per utilizzare funzionalità avanzate. Ad esempio:

    • Quando utilizzi la maggior parte dei modelli Gemini 3.x, la fondatezza con Google Search o Google Maps richiede la fatturazione.

  Scopri di più sui piani tariffari Firebase e sul Gemini Developer API.

  Per maggiori dettagli, consulta la Gemini Developer API documentazione sui prezzi e le domande frequenti sulla fatturazione.