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 backend comuni, le spiegazioni delle relative cause e le soluzioni consigliate:

Codice HTTP Stato Descrizione Esempio Soluzione
400 INVALID_ARGUMENT Il corpo della richiesta non è in un formato corretto. Nella tua 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 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 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.
402 RESOURCE_EXHAUSTED Il tuo saldo del credito prepagato è esaurito. Il tuo account di fatturazione ha esaurito i crediti prepagati, quindi ogni chiave API collegata a quell'account di fatturazione smette di funzionare. Aggiungi crediti al tuo account di fatturazione o attiva la ricarica automatica. Non riprovare a inviare questa richiesta: non andrà a buon fine finché non verranno aggiunti crediti.
403 PERMISSION_DENIED La tua chiave API non dispone delle autorizzazioni necessarie. 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. 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 viene fatto riferimento nella tua richiesta. Verifica che tutti i parametri della richiesta siano validi per la tua versione dell'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 di tempo. Riduci la frequenza o le dimensioni delle richieste. Se necessario, richiedi un aumento del limite di frequenza.
499 ANNULLATI L'operazione è stata annullata, in genere dal chiamante. Il client ha chiuso la connessione prima che l'API potesse terminare la risposta. Controlla se la tua infrastruttura client o di rete sta chiudendo prematuramente la connessione (ad es. a causa di un timeout lato client).
500 PER USO INTERNO Si è verificato un errore imprevisto da parte di Google. Il contesto dell'input è troppo lungo. Controlla la pagina di stato dell'API Gemini per eventuali incidenti in corso. Riduci il contesto dell'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 riesce, l'API imposta il codice di stato HTTP (ad esempio 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.
status stringa Il codice di stato gRPC in SCREAMING_CASE.
details matrice Contesto aggiuntivo dell'errore, ad esempio ErrorInfo o LocalizedMessage.

Passaggi successivi