Errori API

Questa pagina fornisce un riferimento per tutti i codici di errore dell'API Interactions, descrive il formato della risposta di errore e spiega in che modo l'API genera gli errori per i diversi tipi di richiesta.

Codici di errore API standard

Questi codici di errore generali a livello di richiesta corrispondono ai codici di stato HTTP standard. Utilizza il campo code nella logica dell'applicazione per gestire gli errori in modo programmatico.

Codice Stato HTTP Descrizione Azione consigliata
invalid_request 400 Bad Request Il payload della richiesta non è in un formato corretto o contiene parametri non validi. Controlla la sintassi e i parametri della richiesta rispetto al Riferimento API.
failed_precondition 400 Bad Request La richiesta non può essere elaborata perché non è stato soddisfatto un prerequisito (ad esempio, la fatturazione è disattivata). Verifica lo stato di fatturazione del progetto o i prerequisiti dell'account.
out_of_range 416 Requested Range Not Satisfiable Il parametro della richiesta non rientra nell'intervallo valido. Controlla i valori e i limiti dei parametri.
parameter_unknown 400 Bad Request La richiesta contiene un parametro sconosciuto. Rimuovi il parametro non riconosciuto e riprova.
authentication 401 - Non autorizzato La chiave API è mancante, non valida o scaduta. Verifica la chiave API.
payment_required 402 Payment Required Il tuo saldo del credito prepagato è esaurito. Aggiungi crediti al tuo account di fatturazione o attiva la ricarica automatica. Non riprovare: la richiesta non andrà a buon fine finché non verranno aggiunti crediti.
permission_denied 403 Forbidden La tua chiave API non dispone dell'autorizzazione per questa risorsa o l'accesso API del tuo progetto è limitato. Controlla le autorizzazioni della chiave API, l'idoneità al livello del progetto e lo stato di fatturazione. Consulta Risolvi i problemi relativi ai progetti limitati o non disponibili.
not_found 404: non trovato La risorsa richiesta non è stata trovata. Verifica il percorso e i parametri della risorsa.
model_not_found 404: non trovato Impossibile trovare il modello specificato. Verifica il nome del modello o utilizza un altro modello.
already_exists 409 Conflict L'entità che hai tentato di creare esiste già. Controlla se la risorsa esiste già prima di ricrearla.
aborted 409 Conflict L'operazione è stata interrotta a causa di un conflitto o di un errore di controllo della concorrenza. Riprova a inviare la richiesta a un livello di applicazione più elevato.
rate_limit_exceeded 429 Too Many Requests Hai superato il limite di richieste o token al minuto o al secondo. Attendi e riprova con il backoff esponenziale.
quota_exceeded 429 Too Many Requests Hai superato la tua quota giornaliera. Attendi il ripristino della quota o richiedi un aumento della quota.
too_many_requests 429 Too Many Requests Hai effettuato troppe richieste in un breve periodo di tempo. Attendi e riprova con il backoff esponenziale.
cancelled 499 Client Closed Request Il client ha annullato la richiesta prima del completamento. Nessuna azione richiesta. In genere questo significa che il client si è disconnesso.
api_error 500 Internal Server Error Si è verificato un errore imprevisto sul server. Riprova a inviare la richiesta. Se il problema persiste, contatta l'assistenza.
unimplemented 501 Non implementato L'operazione o la funzionalità non è implementata o supportata. Controlla le funzionalità dell'API o passa a una funzionalità supportata.
service_unavailable 503 Service Unavailable Il servizio è temporaneamente sovraccarico o non disponibile. Attendi e riprova con il backoff esponenziale.
deadline_exceeded 504 Gateway Timeout La richiesta non è stata completata entro la scadenza. Rimuovi o aumenta l'impostazione della scadenza del client per utilizzare l'impostazione predefinita del server.

Codici di blocco della generazione

Questi codici di errore indicano che le limitazioni relative alle norme, alla sicurezza o alle limitazioni dei contenuti hanno bloccato l'output del modello. Quando ricevi uno di questi codici, modifica l'input e riprova.

Codice Descrizione
safety Le violazioni della sicurezza (contenuti dannosi) hanno bloccato la richiesta.
recitation La richiesta è stata bloccata da limitazioni relative al copyright o alla recitazione.
language Una lingua non supportata ha bloccato la richiesta.
prohibited_content Le norme relative ai contenuti vietati hanno bloccato la richiesta.
spii La richiesta è stata bloccata dalle limitazioni relative alle informazioni sensibili che consentono l'identificazione personale.
blocklist La richiesta è stata bloccata da termini vietati presenti in una lista bloccata.
image_safety La generazione di immagini è stata bloccata a causa di violazioni della sicurezza.
image_prohibited_content Le norme relative ai contenuti vietati hanno bloccato la generazione di immagini.
image_recitation La generazione di immagini è stata bloccata a causa di limitazioni relative al copyright o alla recitazione.
image_other Motivi non specificati hanno bloccato la generazione di immagini.
content_blocked La richiesta è stata bloccata per un motivo non specificato relativo alle norme.

Codici di errore di generazione

Questi codici di errore indicano un problema strutturale con l'output generato dal modello (ad esempio una chiamata di funzione non corretta o una chiamata di strumento non dichiarata).

Codice Descrizione
malformed_function_call Il modello ha generato una chiamata di funzione che non è stato possibile analizzare.
malformed_tool_call Il modello ha prodotto una chiamata allo strumento che non è stato possibile analizzare.
unexpected_tool_call Il modello ha chiamato uno strumento che non è stato dichiarato nella richiesta.
no_image Il modello non è stato in grado di generare un'immagine.
too_many_tool_calls Il modello ha generato più chiamate di strumenti di quelle consentite.
missing_thought_signature Nella risposta manca una firma del pensiero obbligatoria.

Formato della risposta di errore

Tutti gli errori dell'API Interactions restituiscono un oggetto error contenente un code e un message. Ad esempio, se passi un tipo di strumento non supportato, viene restituito:

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'. Supported values: 'function', 'code_execution', 'mcp_server', 'filesystem', 'google_maps', 'google_search', 'bash', 'computer_use', 'file_search', 'url_context'."
  }
}
Campo Tipo Descrizione
code stringa Un codice di errore leggibile da macchina in snake_case.
message stringa Una descrizione leggibile di ciò che è andato storto.

Come vengono inviati gli errori

L'API restituisce gli errori in modo diverso a seconda che tu effettui una richiesta HTTP standard o una richiesta di streaming (SSE).

Richieste HTTP standard

Per le richieste standard (non in modalità flusso), l'API imposta il codice di stato della risposta HTTP (ad esempio 400 Bad Request, 401 Unauthorized o 429 Too Many Requests) e restituisce un oggetto error nel corpo della risposta JSON:

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'."
  }
}

Richieste di streaming (SSE)

Per le richieste di streaming (stream: true), l'API invia eventi di errore tramite lo stream Server-Sent Events (SSE) con event_type impostato su "error". Il campo error contiene la stessa struttura code e message:

{
  "event_type": "error",
  "error": {
    "code": "not_found",
    "message": "Failed to get completed interaction: Result not found."
  }
}

Per lo schema completo degli eventi SSE, consulta il Riferimento API Interactions.

Passaggi successivi