Questa pagina descrive i codici di errore di Spanner e le azioni consigliate per gestire questi errori. Le API di Google, tra cui Spanner, utilizzano i codici di errore canonici definiti da google.rpc.Code.
Quando una richiesta Spanner va a buon fine, l'API restituisce un codice di stato HTTP200 OK insieme ai dati richiesti nel corpo della risposta.
Quando una richiesta non va a buon fine, l'API Spanner restituisce un codice di stato HTTP4xx o 5xx che identifica in modo generico l'errore, nonché una risposta che fornisce informazioni più specifiche sugli errori che hanno causato il fallimento.
L'oggetto della risposta contiene un singolo campo error il cui valore contiene i seguenti elementi:
| Elemento | Descrizione |
|---|---|
code |
Un codice di stato HTTP che identifica in modo generico 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 in Codici di errore. |
Se una richiesta effettuata con un tipo di contenuto application/x-protobuf genera un errore, verrà restituito un messaggio google.rpc.Status serializzato come payload.
Codici di errore
Il modo consigliato per classificare gli errori è ispezionare il valore del
codice di errore canonico (google.rpc.Code). Negli errori JSON, questo codice appare
nel campo status. Negli errori application/x-protobuf, si trova nel campo code.
| Codice di errore | Descrizione | Azione consigliata |
|---|---|---|
ABORTED |
L'operazione è stata interrotta, in genere a causa di un problema di concorrenza, ad esempio un errore di controllo del sequenziatore o l'interruzione di una transazione. Indica che la richiesta è in conflitto con un'altra richiesta. | Per un commit non transazionale: riprova a inviare la richiesta o struttura le entità per ridurre le contese. Per le richieste che fanno parte di un commit transazionale: riprova a inviare l'intera transazione o struttura le entità per ridurre le contese. |
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, in genere 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 all'ora effettiva 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 la sezione Risolvere i problemi relativi alla scadenza superata. |
FAILED_PRECONDITION |
L'operazione è stata rifiutata perché non è stato soddisfatto un prerequisito per la richiesta. Il campo messaggio nella risposta all'errore fornisce informazioni sul precondizionatore non riuscito. Ad esempio, la lettura o la query da un timestamp che ha superato la staleness massima del timestamp. | Non riprovare senza risolvere il problema. |
INTERNAL |
Il server ha restituito un errore. Alcuni invarianti previsti dal sistema sottostante sono stati violati. | Non riprovare a meno che tu non comprenda le circostanze e la causa specifici dell'errore. |
INVALID_ARGUMENT |
Il client ha specificato un valore non valido. Il campo messaggio nella risposta all'errore fornisce informazioni sul valore non valido. | Non riprovare senza risolvere il problema. |
NOT_FOUND |
Indica che alcune entità richieste, ad esempio 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 |
L'operazione è stata tentata oltre l'intervallo valido. | Non riprovare senza risolvere il problema. |
PERMISSION_DENIED |
L'utente non era autorizzato a inviare la richiesta. | Non riprovare senza risolvere il problema. |
RESOURCE_EXHAUSTED |
Una risorsa è stata esaurita. Per il piano di amministrazione, è possibile che il progetto abbia superato la quota o che l'intero file system non abbia più spazio. Per il piano di dati, questo può accadere se i nodi Spanner sono sovraccaricati. |
Per il piano amministratore, verifica di non aver superato la quota di Spanner o del progetto. Se hai superato una quota, richiedi un aumento della quota o attendi il ripristino della quota prima di riprovare. Configura i tentativi di nuovo invio in modo che utilizzino il backoff esponenziale. Per il piano dati, verifica che i tuoi nodi Spanner non abbiano superato la loro capacità. Spanner riprova a seguito di questi errori nella libreria client. Se tutti i tentativi di ripetizione non vanno a buon fine, consulta la sezione Errori del meccanismo di controllo del flusso. In generale, se la tua applicazione presenta errori RESOURCE_EXHAUSTED, tratta la situazione come un errore UNAVAILABLE e 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 è disponibile. | Riprova utilizzando il backoff esponenziale. Tieni presente che non è sempre sicuro riprovare le operazioni non idempotenti. |
UNIMPLEMENTED |
L'operazione non è implementata o non è supportata/attivata in questo servizio. | Non riprovare senza risolvere il problema. |
UNKNOWN |
Il server ha restituito un errore sconosciuto. Gli errori generati da API che non restituiscono informazioni sufficienti sugli errori possono essere convertiti in questo errore. | Verifica che la tua richiesta sia sicura. Dopodiché, riprova con il backoff esponenziale. |
Errori del meccanismo di controllo del flusso
Spanner potrebbe attivare il proprio meccanismo di controllo del flusso per proteggersi dal sovraccarico nelle seguenti condizioni:
- L'utilizzo della CPU sul nodo Spanner è elevato. Se sospetti che la tua richiesta stia causando un utilizzo elevato della CPU, puoi utilizzare le metriche sull'utilizzo della CPU per esaminare il problema.
- Potrebbero esserci hotspot che aumentano il tempo di elaborazione della richiesta. Se sospetti che la tua richiesta stia causando hotspot, consulta Trovare gli hotspot nel database per esaminare il problema. Per ulteriori informazioni, consulta Visualizzatore di chiavi.
Il meccanismo di controllo del flusso è supportato dalle seguenti librerie client:
Il tempo complessivo per il completamento della richiesta non aumenterà a causa dell'utilizzo del meccanismo di controllo del flusso. Senza questo meccanismo, Spanner attende
prima di elaborare la richiesta e alla fine restituisce un errore DEADLINE_EXCEEDED.
Quando il meccanismo di controllo del flusso è attivo, Spanner invia nuovamente le richieste al client per riprovare. Se il nuovo tentativo consuma l'intera data di scadenza fornita dall'utente, il client riceve un errore RESOURCE_EXHAUSTED.
Questo errore viene restituito se Spanner stima che il tempo di elaborazione della richiesta sia troppo lungo. L'errore propaga il controllo del flusso e
Spanner riprova a inviare la richiesta al client, anziché
accumulare le riprove internamente. In questo modo, Spanner evita di accumulare un consumo aggiuntivo di risorse.