Utilizza questa guida per diagnosticare e risolvere i problemi comuni che si verificano quando chiami l'API Gemini. Potresti riscontrare problemi con il servizio di backend dell'API Gemini o con gli SDK client. I nostri SDK client sono open source nei seguenti repository:
Se riscontri problemi con la chiave API, verifica di aver configurato la tua chiave API correttamente seguendo la guida alla configurazione della chiave API.
Codici di errore
Per un riferimento completo a tutti i codici di errore, inclusi i codici di stato HTTP, codici di generazione bloccati e codici di errore dei contenuti, consulta la pagina Errori dell'API.
Strategia di ripetizione dei tentativi
Se ricevi un errore che indica che devi riprovare a inviare la richiesta (ad esempio un codice di stato 429 RESOURCE_EXHAUSTED o 503 UNAVAILABLE), ti consigliamo di implementare una strategia di backoff esponenziale. Ciò significa che devi attendere un breve periodo di tempo prima del primo tentativo e poi aumentare gradualmente il tempo di attesa tra i tentativi successivi.
Gli SDK client ufficiali per l'API Gemini, come l'SDK Python, includono per impostazione predefinita la logica di ripetizione automatica dei tentativi con backoff esponenziale per la gestione degli errori temporanei come timeout, problemi di rete e limiti di frequenza (codici di stato 429 e 5xx). Ad esempio, l'SDK Python riprova automaticamente a inviare le richieste in caso di errori temporanei fino a quattro volte con un ritardo iniziale di circa 1 secondo e un ritardo massimo di 60 secondi.
Se stai effettuando richieste API REST dirette o personalizzando la logica di ripetizione dei tentativi, segui queste best practice per aumentare la probabilità di una richiesta riuscita ed evitare di sovraccaricare il servizio:
- Utilizza il backoff esponenziale: attendi un breve periodo di tempo prima del primo tentativo (ad esempio 1 secondo), quindi aumenta il ritardo in modo esponenziale (ad esempio 2 secondi, 4 secondi, 8 secondi).
- Aggiungi jitter: aggiungi un "jitter" casuale al ritardo per evitare che tutti i client riprovino esattamente nello stesso momento.
- Ripeti i tentativi in caso di errori specifici: riprova solo in caso di errori temporanei (come
429,408o5xx). Non riprovare in caso di errori del client (come400o403), in quanto indicano problemi come chiavi API non valide o sintassi errata. - Imposta il numero massimo di tentativi: definisci un numero massimo di tentativi per evitare loop infiniti.
Controlla le chiamate API per verificare la presenza di errori nei parametri del modello
Verifica che i parametri del modello rientrino nei seguenti valori:
| Parametro del modello | Valori (intervallo) |
| Conteggio dei candidati | 1-8 (intero) |
| Temperatura | 0.0-1.0 |
| Numero massimo di token di output | Utilizza la pagina dei modelli per determinare il numero massimo di token per il modello che stai utilizzando. |
| TopP | 0.0-1.0 |
Oltre a controllare i valori dei parametri, assicurati di utilizzare la versione dell'
API corretta (ad es. /v1 o /v1beta) e il
modello che supporta le funzionalità di cui hai bisogno. Ad esempio, se una funzionalità è in versione beta, sarà disponibile solo nella versione dell'API /v1beta.
Verifica di avere il modello giusto
Verifica di utilizzare un modello supportato elencato nella nostra pagina dei modelli.
Latenza o utilizzo dei token più elevati con i modelli di ragionamento
Una latenza o un utilizzo dei token più elevati si verificano spesso perché i modelli Gemini 3.x hanno il ragionamento attivato per impostazione predefinita. Anche i modelli Gemini 2.5 ritirati utilizzano il ragionamento predefinito.
I modelli di ragionamento generano token di ragionamento interni per migliorare la qualità. Questo processo di ragionamento aumenta sia la latenza della risposta sia il consumo totale di token.
Se dai la priorità a una latenza inferiore o devi ridurre al minimo i costi, puoi ridurre il livello di ragionamento o disattivarlo.
Per i dettagli di configurazione e gli esempi di codice, consulta la guida al ragionamento.
Problemi di sicurezza
Se vedi che un prompt è stato bloccato a causa di un'impostazione di sicurezza nella chiamata API, esaminalo rispetto ai filtri impostati nella chiamata API.
Se vedi BlockedReason.OTHER, la query o la risposta potrebbe violare i Termini
di servizio o non essere supportata.
Problema di recitazione
Se vedi che il modello smette di generare output a causa del motivo RECITATION, significa che l'output del modello potrebbe assomigliare a determinati dati. Per risolvere il problema, prova a rendere il prompt / il contesto il più univoco possibile e utilizza una temperatura più elevata.
Problema dei token ripetitivi
Se vedi token di output ripetuti, prova a seguire i suggerimenti riportati di seguito per ridurli o eliminarli.
| Descrizione | Causa | Soluzione alternativa suggerita |
|---|---|---|
| Trattini ripetuti nelle tabelle Markdown | Questo può verificarsi quando i contenuti della tabella sono lunghi, perché il modello tenta di creare una tabella Markdown allineata visivamente. Tuttavia, l'allineamento in Markdown non è necessario per il rendering corretto. |
Aggiungi istruzioni nel prompt per fornire al modello linee guida specifiche per la generazione di tabelle Markdown. Fornisci esempi che seguano queste linee guida. Puoi anche provare a regolare la temperatura. Per la generazione di codice o output molto strutturati come le tabelle Markdown, è stato dimostrato che le temperature elevate funzionano meglio (>= 0.8). Di seguito è riportato un esempio di linee guida che puoi aggiungere al tuo prompt per evitare questo problema:
# Markdown Table Format
* Separator line: Markdown tables must include a separator line below
the header row. The separator line must use only 3 hyphens per
column, for example: |---|---|---|. Using more hypens like
----, -----, ------ can result in errors. Always
use |:---|, |---:|, or |---| in these separator strings.
For example:
| Date | Description | Attendees |
|---|---|---|
| 2024-10-26 | Annual Conference | 500 |
| 2025-01-15 | Q1 Planning Session | 25 |
* Alignment: Do not align columns. Always use |---|.
For three columns, use |---|---|---| as the separator line.
For four columns use |---|---|---|---| and so on.
* Conciseness: Keep cell content brief and to the point.
* Never pad column headers or other cells with lots of spaces to
match with width of other content. Only a single space on each side
is needed. For example, always do "| column name |" instead of
"| column name |". Extra spaces are wasteful.
A markdown renderer will automatically take care displaying
the content in a visually appealing form.
|
| Token ripetuti nelle tabelle Markdown | Analogamente ai trattini ripetuti, questo si verifica quando il modello tenta di allineare visivamente i contenuti della tabella. L'allineamento in Markdown non è necessario per il rendering corretto. |
|
Nuovi righi ripetuti (\n) nell'output strutturato
|
Quando l'input del modello contiene sequenze di escape o Unicode come
\u o \t, può portare a nuovi righi ripetuti.
|
|
| Testo ripetuto nell'utilizzo dell'output strutturato | Quando l'output del modello ha un ordine dei campi diverso dallo schema strutturato definito, può portare alla ripetizione del testo. |
|
| Chiamata ripetitiva allo strumento | Questo può verificarsi se il modello perde il contesto dei pensieri precedenti e/o chiama un endpoint non disponibile a cui è costretto. |
Indica al modello di mantenere lo stato all'interno del processo di pensiero.
Aggiungi quanto segue alla fine delle istruzioni di sistema:
When thinking silently: ALWAYS start the thought with a brief
(one sentence) recap of the current progress on the task. In
particular, consider whether the task is already done.
|
| Testo ripetitivo che non fa parte dell'output strutturato | Questo può verificarsi se il modello si blocca su una richiesta che non riesce a risolvere. |
|
Chiavi API bloccate o non funzionanti
Questa sezione descrive come verificare se la chiave API Gemini è bloccata e cosa fare.
Scopri perché le chiavi vengono bloccate
Abbiamo identificato una vulnerabilità per cui alcune chiavi API potrebbero essere state esposte pubblicamente. Per proteggere i tuoi dati e impedire accessi non autorizzati, abbiamo bloccato in modo proattivo l'accesso all'API Gemini per queste chiavi di cui è stata accertata la compromissione.
Verifica se le tue chiavi sono interessate
Se è noto che la tua chiave è stata compromessa, non puoi più utilizzarla con l'API Gemini. Puoi utilizzare Google AI Studio per verificare se l'accesso all'API Gemini è stato bloccato per una delle tue chiavi API e generare nuove chiavi. Quando tenti di utilizzare queste chiavi, potresti anche visualizzare il seguente errore:
Your API key was reported as leaked. Please use another API key.
Azioni per le chiavi API bloccate
Devi generare nuove chiavi API per le integrazioni dell'API Gemini utilizzando Google AI Studio. Ti consigliamo vivamente di esaminare le tue pratiche di gestione delle chiavi API per assicurarti che le nuove chiavi siano protette e non siano esposte pubblicamente.
Addebiti imprevisti a causa della vulnerabilità
Invia una richiesta di assistenza per la fatturazione. Il nostro team di fatturazione sta lavorando al problema e ti comunicheremo gli aggiornamenti il prima possibile.
Misure di sicurezza di Google per le chiavi compromesse
In che modo Google mi aiuterà a proteggere il mio account da sforamenti di costi e comportamenti illeciti se le mie chiavi API vengono compromesse?
- Stiamo passando all'emissione di chiavi API quando richiedi una nuova chiave utilizzando Google AI Studio che per impostazione predefinita sarà limitata solo a Google AI Studio e non accetterà chiavi di altri servizi. In questo modo si eviterà l'utilizzo involontario di chiavi incrociate.
- Per impostazione predefinita, blocchiamo le chiavi API compromesse e utilizzate con l'API Gemini, contribuendo a prevenire comportamenti illeciti relativi ai costi e ai dati delle applicazioni.
- Potrai trovare lo stato delle tue chiavi API in Google AI Studio e lavoreremo per comunicare in modo proattivo quando identifichiamo le tue chiavi API compromesse per un'azione immediata.
Migliora l'output del modello
Per ottenere output del modello di qualità superiore, prova a scrivere prompt più strutturati. La pagina della guida all'ingegneria del prompt introduce alcuni concetti di base, strategie e best practice per iniziare.
Informazioni sui limiti dei token
Leggi la nostra guida ai token per comprendere meglio come contarli e quali sono i relativi limiti.
Problemi noti
- L'API supporta solo un numero limitato di lingue. L'invio di prompt in lingue non supportate può produrre risposte impreviste o persino bloccate. Per gli aggiornamenti, consulta le lingue disponibili per aggiornamenti.
Segnala un bug
Se hai domande, partecipa alla discussione sul forum per sviluppatori di Google AI.