Utilizza questa guida per diagnosticare e risolvere i problemi comuni che si verificano quando chiami l'API Gemini. Se riscontri problemi relativi alle chiavi API, assicurati di aver configurato correttamente la chiave API seguendo la guida alla configurazione delle chiavi API.
Codici di errore
La seguente tabella elenca i codici di errore comuni che potresti riscontrare, insieme alle spiegazioni relative alle loro cause e ai passaggi per la risoluzione dei problemi:
| Codice HTTP | Stato | Descrizione | Soluzione |
| 400 | INVALID_ARGUMENT | Il formato del corpo della richiesta non è valido. | Controlla il riferimento API per conoscere il formato della richiesta, gli esempi e le versioni supportate. L'utilizzo di funzionalità di una versione più recente dell'API con un endpoint precedente può causare errori. |
| 403 | PERMISSION_DENIED | La tua chiave API non dispone delle autorizzazioni richieste. | Verifica che la chiave API sia impostata e abbia l'accesso corretto. |
| 404 | NOT_FOUND | La risorsa richiesta non è stata trovata. | Controlla se tutti i parametri nella richiesta sono validi per la versione dell'API. |
| 429 | RESOURCE_EXHAUSTED | Hai superato il limite di frequenza. | Assicurati di rientrare nel limite di frequenza del modello. Richiedi un aumento della quota, se necessario. |
| 500 | INTERNAL | Si è verificato un errore imprevisto da parte di Google. | Attendi un istante e riprova. Se il problema persiste dopo aver riprovato, segnalalo utilizzando il pulsante Invia feedback in Google AI Studio. |
| 503 | UNAVAILABLE | Il servizio potrebbe essere temporaneamente sovraccarico o non disponibile. | Attendi un istante e riprova. Se il problema persiste dopo aver riprovato, segnalalo utilizzando il pulsante Invia feedback in Google AI Studio. |
Verifica la presenza di errori nei parametri del modello nelle chiamate API
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 |
| Numero massimo di token di output |
Utilizza get_model (Python) per determinare il numero massimo di token per il modello in uso.
|
| TopP | 0,0-1,0 |
Oltre a verificare i valori dei parametri, assicurati di utilizzare la versione API corretta (ad es. /v1 o /v1beta) e un modello che supporta le funzionalità di cui hai bisogno. Ad esempio, se una funzionalità è in release beta, sarà disponibile soltanto nella versione dell'API /v1beta.
Verifica di avere il modello giusto
Assicurati di utilizzare un modello supportato. Utilizza list_models
(Python) per ottenere tutti i modelli
disponibili per l'uso.
Problemi di sicurezza
Se vedi che un messaggio è stato bloccato a causa di un'impostazione di sicurezza nella chiamata API, esamina la richiesta in relazione ai filtri che hai impostato nella chiamata API.
Se vedi BlockedReason.OTHER, la query o la risposta potrebbero violare i Termini di servizio o non essere altrimenti supportate.
Migliora l'output del modello
Per output di modelli di qualità superiore, prova a scrivere prompt più strutturati. La pagina introduzione alla progettazione dei prompt introduce alcuni concetti, strategie e best practice di base per iniziare.
Se disponi di centinaia di esempi di buone coppie di input/output, puoi anche valutare l'ottimizzazione del modello.
Informazioni sui limiti dei token
Utilizza l'API ModelService per ottenere metadati aggiuntivi sui modelli, inclusi i limiti dei token di input e di output.
Per ottenere i token utilizzati dal prompt, utilizza countMessageTokens per i modelli di chat e countTextTokens per i modelli di testo.
Problemi noti
- Supporto per Google AI Studio su dispositivi mobili: il sito web può essere aperto sui dispositivi mobili, ma non è stato ottimizzato per gli schermi di piccole dimensioni.
- L'API supporta solo l'inglese. Inviare prompt in lingue diverse può produrre risposte impreviste o addirittura bloccate. Per gli aggiornamenti, vedi le lingue disponibili.
Segnala un bug
Segnala un problema in GitHub per porre domande o inviare richieste di funzionalità o bug.