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 di 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 chiavi API nel riquadro API e servizi > Credenziali nella Google Cloud console.

Se scopri che non corrispondono, allora recupera un nuovo file/oggetto di configurazione di 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 Cloud Storage for Firebase URL, 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 in quel progetto. Si tratta di un problema noto con alcuni progetti e stiamo lavorando a una correzione globale.

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

1. Accedi ed esegui l'autenticazione con gcloud CLI.
   Il modo più semplice per farlo è da Cloud Shell. Scopri di più nella Google Cloud documentazione.

2. Se ti viene richiesto, segui le istruzioni visualizzate nel terminale per fare in modo che il gcloud CLI venga eseguito sul tuo progetto Firebase.

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

3. Esegui il provisioning degli agenti di servizio richiesti nel progetto eseguendo il seguente 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 sia stato eseguito il provisioning degli agenti di servizio, quindi riprova a inviare la richiesta multimodale che include l'URL.Cloud Storage for Firebase

Se continui a ricevere 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., in genere significa che la chiave API nella configurazione di Firebase nella tua app ha limitazioni che impediscono di chiamare l'API richiesta.

Per risolvere il problema, devi aggiornare le limitazioni della chiave API nella Google Cloud console in modo da includere l'API richiesta. Per Firebase AI Logic, devi assicurarti che l'Firebase AI Logic API (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 Limitazioni delle API.

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

5. Nel menu a discesa API selezionate, cerca e seleziona l' Firebase AI Logic API 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 diventino effettive.

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 di 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 chiavi API nel riquadro API e servizi > Credenziali nella Google Cloud console.

Se scopri che non corrispondono, allora recupera un nuovo file/oggetto di configurazione di 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 stai tentando 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 ha 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 il Gemini Developer API.

  Cosa fare:
  Nella console Firebase, vai a Servizi AI > AI Logic. Fai clic su Inizia, quindi seleziona la Gemini Developer API. Abilita 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 Firebase AI Logic nella console Firebase, la chiave API Gemini potrebbe non essere ancora disponibile per tutti i servizi di backend richiesti in tutte le regioni.

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

• La 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.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 ricevere un errore di questo tipo.

• Nome del 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:

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

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

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

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

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

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

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

    • Gemini modelli anteprima ed sperimentali: disponibili solo nella località global (ad eccezione dei modelli Live API, vedi di seguito).

    • Gemini 3.x modelli: disponibili solo nella località global quando utilizzi Firebase AI Logic. Firebase AI Logic non supporta ancora us e eu località.

    • Gemini 2.5 modelli: Disponibili in molte località.

    • Gemini Live API modelli: disponibili solo nella località us-central1. La località global non è supportata.

  Scopri di più su come specificare la località 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."

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

L'azione da intraprendere dipende dal fatto che tu stia utilizzando il Gemini Developer API o il 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 Google Cloud fornisce alcuni contesti e indicazioni aggiuntivi per il codice di errore 429.