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, assicurati di averla configurata correttamente in base alla guida alla configurazione delle chiavi API.
Codici di errore del servizio di backend dell'API Gemini
La tabella seguente elenca i codici di errore di backend più comuni che potresti riscontrare, insieme alle spiegazioni delle relative cause e ai passaggi per la risoluzione dei problemi:
| Codice HTTP | Stato | Descrizione | Esempio | Soluzione |
| 400 | INVALID_ARGUMENT | Il corpo della richiesta non è valido. | Nella richiesta è presente un errore ortografico o manca un campo obbligatorio. | Consulta il riferimento all'API per informazioni sul formato della richiesta, sugli esempi e sulle versioni supportate. L'utilizzo di funzionalità di una versione dell'API più recente con un endpoint precedente può causare errori. |
| 400 | FAILED_PRECONDITION | Il livello senza costi dell'API Gemini non è disponibile nel tuo paese. Abilita la fatturazione per il tuo progetto in Google AI Studio. | Stai inviando una richiesta in una regione in cui il livello senza costi non è supportato e non hai attivato la fatturazione nel tuo progetto in Google AI Studio. | Per utilizzare l'API Gemini, devi configurare un piano a pagamento utilizzando Google AI Studio. |
| 403 | PERMISSION_DENIED | La chiave API non dispone delle autorizzazioni richieste. | Stai utilizzando la chiave API sbagliata; stai tentando di utilizzare un modello ottimizzato senza eseguire l'autenticazione corretta. | Verifica che la chiave API sia impostata e abbia l'accesso corretto. Inoltre, assicurati di eseguire l'autenticazione corretta per utilizzare i modelli ottimizzati. |
| 404 | NOT_FOUND | La risorsa richiesta non è stata trovata. | Non è stato trovato un file immagine, audio o video a cui si fa riferimento nella richiesta. | Verifica che tutti i parametri nella richiesta siano validi per la versione dell'API. |
| 429 | RESOURCE_EXHAUSTED | Hai superato il limite di frequenza. | Stai inviando troppe richieste al minuto con l'API Gemini di livello senza costi. | Assicurati di rispettare il limite di frequenza del modello. Richiedi un aumento della quota, se necessario. |
| 500 | INTERNAL | Si è verificato un errore imprevisto da parte di Google. | Il contesto dell'input è troppo lungo. | Riduci il contesto di input o passa temporaneamente a un altro modello (ad es. da Gemini 1.5 Pro a Gemini 1.5 Flash) e controlla se funziona. In alternativa, attendi un po' e riprova a inviare la richiesta. Se il problema persiste dopo il nuovo tentativo, segnalalo utilizzando il pulsante Invia feedback in Google AI Studio. |
| 503 | UNAVAILABLE | Il servizio potrebbe essere temporaneamente sovraccaricato o non disponibile. | La capacità del servizio sta per esaurirsi temporaneamente. | Passa temporaneamente a un altro modello (ad es. da Gemini 1.5 Pro a Gemini 1.5 Flash) e controlla se funziona. In alternativa, attendi un po' e riprova a inviare la richiesta. Se il problema persiste dopo il nuovo tentativo, segnalalo utilizzando il pulsante Invia feedback in Google AI Studio. |
| 504 | DEADLINE_EXCEEDED | Il servizio non è in grado di completare l'elaborazione entro la scadenza. | Il prompt (o il contesto) è troppo grande per essere elaborato in tempo. | Per evitare questo errore, imposta un valore "timeout" più elevato nella richiesta del client. |
Codici di errore dell'SDK client
Nella tabella seguente sono elencati i codici di errore SDK client Python più comuni che potresti riscontrare, oltre alle spiegazioni delle relative cause:
| Tipo di eccezione/errore | Classe | Descrizione |
|---|---|---|
| APIError | google.genai.errors.APIError | Errori generali generati dall'API GenAI. |
| ClientError | google.genai.errors.ClientError | Errore del client generato dall'API GenAI. |
| ServerError | google.genai.errors.ServerError | Errore del server generato dall'API GenAI. |
| UnknownFunctionCallArgumentError | google.genai.errors.UnknownFunctionCallArgumentError | Viene sollevato quando l'argomento della chiamata alla funzione non può essere convertito nell'annotazione del parametro. |
| UnsupportedFunctionError | google.genai.errors.UnsupportedFunctionError | Viene sollevato quando la funzione non è supportata. |
| FunctionInvocationError | google.genai.errors.FunctionInvocationError | Viene sollevato quando la funzione non può essere richiamata con gli argomenti specificati. |
| ValidationError | pydantic.ValidationError | Viene sollevato da Pydantic ogni volta che viene rilevato un errore nei dati che sta convalidando. Consulta la sezione Gestione degli errori di Pydantic. |
Troverai tutti gli errori anche nella classe errors.
Per gestire gli errori generati dall'SDK, puoi utilizzare un blocco try-except:
from google.genai import errors
try:
client.models.generate_content(
model="invalid-model-name",
contents="What is your name?",
)
except errors.APIError as e:
print(e.code) # 404
print(e.message)
Controlla le chiamate API per verificare la presenza di errori nei parametri del modello
Assicurati che i parametri del modello rientrino nei seguenti valori:
| Parametro del modello | Valori (intervallo) |
| Numero di candidati | 1-8 (numero intero) |
| Temperatura | 0,0-1,0 |
| Token di output massimi |
Utilizza
get_model (Python)
per determinare il numero massimo di token per il modello in uso.
|
| 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.
Verificare di avere il modello giusto
Assicurati di utilizzare un modello supportato elencato nella nostra pagina dei modelli.
Problemi di sicurezza
Se vedi che un prompt è stato bloccato a causa di un'impostazione di sicurezza nella chiamata API, esamina il prompt in base ai filtri impostati nella chiamata API.
Se visualizzi BlockedReason.OTHER, la query o la risposta potrebbe violare i Termini di servizio o non essere supportata.
Problema di recitazione
Se il modello smette di generare output per il motivo RECITATION, significa che l'output del modello potrebbe assomigliare a determinati dati. Per risolvere il problema, prova a rendere il prompt / contesto il più unico possibile e utilizza una temperatura più alta.
Migliorare l'output del modello
Per output del modello di qualità superiore, prova a scrivere prompt più strutturati. La pagina Introduzione alla progettazione dei prompt illustra alcuni concetti di base, strategie e best practice per iniziare.
Se hai centinaia di esempi di buone coppie di input/output, puoi anche prendere in considerazione l'ottimizzazione del modello.
Informazioni sui limiti di token
Leggi la nostra guida ai token per comprendere meglio come contare i token e i relativi limiti.
Problemi noti
- L'API supporta solo alcune lingue. L'invio di prompt in lingue non supportate può produrre risposte inaspettate o addirittura bloccate. Per gli aggiornamenti, consulta le lingue disponibili.
Segnala un bug
Se hai domande, partecipa alla discussione nel forum per sviluppatori di IA di Google.