Codici di errore e gestione degli errori di Spanner

Questa pagina descrive i codici di errore di Spanner e le azioni consigliate per a gestire questi errori. Le API di Google, incluso Spanner, utilizzano codici di errore canonici definiti da google.rpc.Code.

Quando una richiesta Spanner ha esito positivo, l'API restituisce una richiesta HTTP Codice di stato 200 OK insieme ai dati richiesti nel corpo della risposta.

Quando una richiesta non va a buon fine, l'API Spanner restituisce una richiesta HTTP Codice di stato 4xx o 5xx che identifica in modo generico l'errore e un risposta che fornisce informazioni più specifiche sugli errori che hanno causato l'errore.

L'oggetto risposta contiene un singolo campo error il cui valore contiene i seguenti elementi:

Elemento Descrizione
code Un codice di stato HTTP che identifica genericamente l'errore della richiesta.
message Informazioni specifiche sull'errore della richiesta.
status Il codice di errore canonico (google.rpc.Code) per le API di Google. I codici che possono essere restituiti dall'API Spanner sono elencati nella sezione Codici di errore.

Se una richiesta effettuata con un tipo di contenuti application/x-protobuf restituisce un verrà restituito un messaggio google.rpc.Status serializzato come per il payload.

Codici di errore

Il modo consigliato per classificare gli errori è esaminare il valore del parametro codice di errore canonico (google.rpc.Code). Negli errori JSON, questo codice viene visualizzato nel campo status. Tra application/x-protobuf errori, è in code .

Codice di errore Descrizione Azione consigliata
ABORTED L'operazione è stata interrotta, in genere a causa di un problema di contemporaneità come un errore di controllo del sequencer o l'interruzione di una transazione. Indica che la richiesta è in conflitto con un'altra richiesta. Per un commit non transazionale:
Riprova la richiesta o struttura le entità per ridurre il conflitto.

Per le richieste che fanno parte di un commit transazionale:
Riprova l'intera transazione o struttura le entità per ridurre il conflitto.
ALREADY_EXISTS L'entità che un client ha tentato di creare esiste già (ad esempio, l'inserimento di una riga con una chiave primaria esistente). Non riprovare senza risolvere il problema.
CANCELLED L'operazione è stata annullata, generalmente dal chiamante. Riprova a eseguire l'operazione.
DEADLINE_EXCEEDED La scadenza è scaduta prima del completamento dell'operazione. Verifica se la scadenza è sufficiente. Utilizza una scadenza corrispondente al momento effettivo in cui una risposta è utile. Tieni presente che per le operazioni che modificano lo stato del sistema, potrebbe essere restituito un errore anche se l'operazione è stata completata correttamente.

Per suggerimenti, consulta Risolvere gli errori relativi al superamento della scadenza.
FAILED_PRECONDITION L'operazione è stata rifiutata perché non è stata soddisfatta una condizione preliminare per la richiesta. Il campo del messaggio nella risposta di errore fornisce informazioni sulla condizione preliminare che non è riuscita. Una possibile causa è l'esecuzione di una query che richiede un indice non ancora definito. Non riprovare senza risolvere il problema.
INTERNAL Il server ha restituito un errore. Alcune caratteristiche invarianti previste dal sistema sottostante sono state interrotte. Non riprovare se non conosci la circostanza specifica e la causa dell'errore.
INVALID_ARGUMENT Il cliente ha specificato un valore non valido. Il campo del messaggio nella risposta di errore fornisce informazioni sul valore non valido. Non riprovare senza risolvere il problema.
NOT_FOUND Indica che alcune entità richieste, come l'aggiornamento di un'entità o l'esecuzione di query su una tabella o una colonna, non esistono. Non riprovare senza risolvere il problema.
OUT_OF_RANGE Il tentativo dell'operazione è stato effettuato una volta superato l'intervallo valido. Non riprovare senza risolvere il problema.
PERMISSION_DENIED L'utente non è stato autorizzato a effettuare la richiesta. Non riprovare senza risolvere il problema.
RESOURCE_EXHAUSTED Alcune risorse sono esaurite. Forse il progetto ha superato la quota o l'intero file system è esaurito. Verifica di non aver superato la quota di Spanner o del progetto. Se hai superato una quota, non riprovare senza risolvere il problema.

Altrimenti, riprova con il backoff esponenziale.
UNAUTHENTICATED La richiesta non ha credenziali di autenticazione valide per l'operazione. Non riprovare senza risolvere il problema.
UNAVAILABLE Il server non è al momento disponibile Riprova utilizzando il backoff esponenziale. Tieni presente che non è sempre sicuro ritentare le operazioni non idempotenti.
UNIMPLEMENTED L'operazione non è implementata o non è supportata/abilitata in questo servizio. Non riprovare senza risolvere il problema.
UNKNOWN Il server ha restituito un errore sconosciuto. Gli errori generati dalle API che non restituiscono informazioni sufficienti sull'errore potrebbero essere convertiti in questo errore. Verifica che la tua richiesta sia sicura. Quindi, riprova con il backoff esponenziale.