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 riquadro 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 i service agent richiesti non sono stati sottoposti al provisioning automatico corretto quando l'API Vertex AI è 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 progetto e eseguire il provisioning corretto di questi service agent in modo da poter iniziare a includere gli URL Cloud Storage for Firebase nelle richieste multimodali. Devi essere proprietario del progetto e devi completare questo insieme di attività una sola volta per il progetto.

1. Accedi e autenticati 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 al 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: 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 configurata per l'utilizzo dalla tua applicazione (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 sia selezionata l'opzione Limita chiave. 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 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 riquadro 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 404: Firebase AI Logic genai config not found

Se tenti di utilizzare Gemini Developer API e ricevi un errore 404 che indica Firebase AI Logic genai config not found, in genere significa che il tuo progetto Firebase non dispone di una chiave API Gemini valida da utilizzare con gli SDK client Firebase AI Logic.

Ecco le cause più probabili di questo errore:

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

  Cosa fare:
  Nella console Firebase, vai a Servizi AI > Logica AI. Fai clic su Inizia, quindi seleziona Gemini Developer API. Attiva l'API e la console configurerà il tuo progetto per Gemini Developer API. 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 tua chiave API Gemini potrebbe non essere ancora disponibile per tutti i servizi di backend richiesti in tutte le regioni.

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

• La tua chiave API Gemini potrebbe essere stata eliminata dal tuo progetto Firebase.

  Cosa fare:
  Scopri come modificare la chiave API Gemini utilizzata da Firebase AI Logic.

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-pro-image-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 ricevere un errore di questo tipo.

• Nome del modello non valido

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

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

    • Il nome del modello di anteprima Gemini 3.1 Pro è gemini-3.1-pro-preview.
    • Il nome del modello di anteprima Gemini 3 Flash è gemini-3-flash-preview.
    • Il nome del modello di anteprima "Nano Banana Pro" è gemini-3-pro-image-preview.
    • Il nome del modello di anteprima "Nano Banana 2" è gemini-3.1-flash-image-preview.
    • Il nome del modello "Nano Banana" è gemini-2.5-flash-image.

• Posizione non valida (valido solo se utilizzi il provider Vertex AI Gemini API e un modello anteprima o sperimentale)

  • Causa: stai utilizzando una versione di anteprima o sperimentale di un modello (ad esempio gemini-3.1-pro-preview e gemini-3.1-flash-image-preview) e non hai specificato la posizione global.

    Se utilizzi Vertex AI Gemini API, tutti i modelli di anteprima e sperimentali Gemini (ad eccezione dei modelli Gemini Live) sono disponibili solo nella località global. Tuttavia, poiché Firebase AI Logic utilizza per impostazione predefinita la posizione us-central1, devi specificare esplicitamente la posizione global quando inizializzi il servizio di backend Vertex AI Gemini API nel codice quando utilizzi questi modelli di anteprima e sperimentali Gemini.

  • Correzione: quando inizializzi il servizio Vertex AI Gemini API, specifica la posizione global. Scopri di più su come specificare la posizione per accedere al modello (inclusi gli snippet di codice).

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

  • Causa: stai utilizzando un modello non supportato nella località in cui stai tentando di accedervi.

    Se utilizzi Vertex AI Gemini API, alcuni modelli sono disponibili solo in determinate località. Ad esempio (elenco non esaustivo):

    • I modelli Imagen non sono supportati nella località global.
    • I modelli Gemini Live API (come gemini-2.0-flash-live-preview-04-09) sono supportati solo nella località us-central1.
    • I modelli Gemini 2.5 (come gemini-2.5-pro) sono disponibili solo nella località global, nelle località degli Stati Uniti e in alcune località europee (e a volte in altre località se il tuo progetto ha opzioni speciali).

  • Correzione: quando inizializzi il servizio Vertex AI Gemini API, assicurati di specificare una località supportata per il modello che stai utilizzando. Scopri di più su come specificare la posizione per accedere al modello (inclusi gli snippet di codice) e le posizioni supportate per i modelli.

    Tieni presente che Firebase AI Logic è impostato per impostazione predefinita sulla posizione us-central1.

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

Gli errori 429 indicano che stai superando la quota o che il modello a cui stai accedendo è sovraccarico di richieste da parte di altre persone.

L'azione da intraprendere dipende dall'utilizzo di Gemini Developer API o Vertex AI Gemini API. Per ulteriori informazioni sulle quote e su come richiedere quote aggiuntive, consulta Limiti di frequenza e quote.

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