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 come l'API restituisce gli errori per i diversi tipi di richieste.

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 Richiesta non valida Il payload della richiesta non è valido 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é un prerequisito non è soddisfatto (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 Richiesta non valida 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. Controlla le autorizzazioni della chiave API e l'accesso al progetto.
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 Il modello specificato non è stato trovato. Verifica il nome del modello o passa a un modello diverso.
already_exists conflitto (409) 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 superiore.
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 Not Implemented L'operazione o la funzionalità non è implementata o supportata. Controlla le funzionalità dell'API o passa a una funzionalità supportata.
service_unavailable 503 - Servizio non disponibile 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 del limite di tempo del client per utilizzare il valore predefinito del server.

Codici di generazione bloccati

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

Codice Descrizione
safety Violazioni della sicurezza (contenuti dannosi) hanno bloccato la richiesta.
recitation La richiesta è stata bloccata a causa di limitazioni relative al copyright o alla recitazione.
language Una lingua non supportata ha bloccato la richiesta.
prohibited_content Le linee guida per i contenuti vietati hanno bloccato la richiesta.
spii Le limitazioni relative alle informazioni sensibili che consentono l'identificazione personale hanno bloccato la richiesta.
blocklist I termini vietati in una lista bloccata hanno bloccato la richiesta.
image_safety Le violazioni della sicurezza hanno bloccato la generazione dell'immagine.
image_prohibited_content Le linee guida per i contenuti vietati hanno bloccato la generazione di immagini.
image_recitation Le limitazioni relative al copyright o alla recitazione hanno bloccato la generazione dell'immagine.
image_other Motivi non specificati hanno bloccato la generazione dell'immagine.
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 valida o una chiamata di strumento non dichiarata).

Codice Descrizione
malformed_function_call Il modello ha prodotto 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 non dichiarato nella richiesta.
no_image Il modello non è riuscito a generare un'immagine.
too_many_tool_calls Il modello ha generato più chiamate di strumenti del consentito.
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 code e message. Ad esempio, il passaggio di un tipo di strumento non supportato restituisce:

{
  "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 dal computer in snake_case.
message stringa Una descrizione leggibile di ciò che è andato storto.

Come vengono pubblicati gli errori

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

Richieste HTTP standard

Per le richieste standard (non in streaming), 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 i riferimenti per l'API Interactions.

Passaggi successivi