Errori API

Questa pagina fornisce un riferimento per i codici di errore del backend restituiti dall'API GenerateContent, descrive il formato della risposta di errore gRPC e fornisce i passaggi per la risoluzione dei problemi.

Codici di errore HTTP

La seguente tabella elenca i codici di errore del backend comuni, le spiegazioni delle cause e le soluzioni consigliate:

Codice HTTP Stato Descrizione Esempio Soluzione
400 INVALID_ARGUMENT Il corpo della richiesta non è in un formato corretto. Nella richiesta è presente un errore di battitura o manca un campo obbligatorio. Consulta il riferimento API per il formato della richiesta, gli esempi e le versioni supportate. L'utilizzo di funzionalità di una versione 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. Attiva la fatturazione per il tuo progetto in Google AI Studio. Stai effettuando una richiesta in una regione in cui il livello senza costi non è supportato e non hai attivato la fatturazione per il 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 tua chiave API non dispone delle autorizzazioni richieste. Stai utilizzando la chiave API errata; stai tentando di utilizzare un modello ottimizzato senza eseguire l'autenticazione corretta. Verifica che la chiave API sia impostata e disponga dell'accesso corretto. 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 viene fatto riferimento nella richiesta. Verifica che tutti i parametri della richiesta siano validi per la tua versione API.
429 RESOURCE_EXHAUSTED Hai superato uno dei limiti di frequenza dell'API (RPM, TPM, RPD, spesa e così via). Stai inviando troppe richieste, utilizzando troppi token o superando i limiti basati sulla spesa per la cronologia della fatturazione e il livello del tuo account. Verifica di rispettare i limiti di frequenza del modello. Attendi e riprova dopo un breve periodo. Riduci la frequenza o le dimensioni delle richieste. Se necessario, richiedi un aumento del limite di frequenza.
499 CANCELLED L'operazione è stata annullata, in genere dal chiamante. Il client ha chiuso la connessione prima che l'API potesse terminare la risposta. Verifica se la tua infrastruttura di rete o client chiude prematuramente la connessione (ad es. a causa di un timeout lato client).
500 INTERNAL Si è verificato un errore imprevisto da parte di Google. Il contesto di input è troppo lungo. Controlla la pagina di stato dell'API Gemini per eventuali incidenti in corso. Riduci il contesto di input o passa temporaneamente a un altro modello (ad es. da Gemini 2.5 Pro a Gemini 2.5 Flash) e verifica se funziona. In alternativa, attendi un po' e riprova a inviare la richiesta. 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. Il servizio sta temporaneamente esaurendo la capacità. Controlla la pagina di stato dell'API Gemini per eventuali incidenti in corso. Passa temporaneamente a un altro modello (ad es. da Gemini 2.5 Pro a Gemini 2.5 Flash) e verifica se funziona. In alternativa, attendi un po' e riprova a inviare la richiesta. Se il problema persiste dopo aver riprovato, 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. Imposta un "timeout" più lungo nella richiesta del client per evitare questo errore.

Formato della risposta di errore

Quando una richiesta GenerateContent non va a buon fine, l'API imposta il codice di stato HTTP (ad es. 400 Bad Request, 403 Forbidden o 429 Too Many Requests) e restituisce un corpo della risposta JSON contenente i dettagli dello stato gRPC:

{
  "error": {
    "code": 400,
    "message": "API key not valid. Please pass a valid API key.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "API_KEY_INVALID",
        "domain": "googleapis.com",
        "metadata": {
          "service": "generativelanguage.googleapis.com"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
        "locale": "en-US",
        "message": "API key not valid. Please pass a valid API key."
      }
    ]
  }
}
Campo Tipo Descrizione
code integer Il codice di stato HTTP.
message stringa Una descrizione dell'errore leggibile da una persona.
status stringa Il codice di stato gRPC in SCREAMING_CASE.
details matrice Contesto di errore aggiuntivo, ad esempio ErrorInfo o LocalizedMessage.

Passaggi successivi