Code

I codici di errore canonici per le API gRPC.

In alcuni casi, potrebbero essere applicati più codici di errore. I servizi devono restituire il codice di errore più specifico applicabile. Ad esempio, preferisci OUT_OF_RANGE rispetto a FAILED_PRECONDITION se si applicano entrambi i codici. Allo stesso modo, scegli NOT_FOUND o ALREADY_EXISTS invece di FAILED_PRECONDITION.

Enum
OK

Non è un errore; restituito al successo.

Mappatura HTTP: 200 OK

CANCELLED

L'operazione è stata annullata, in genere dal chiamante.

Mappatura HTTP: richiesta di chiusura del client 499

UNKNOWN

Errore sconosciuto. Ad esempio, questo errore può essere restituito quando un valore Status ricevuto da un altro spazio di indirizzi appartiene a uno spazio di errori sconosciuto in questo spazio. Anche gli errori generati da API che non restituiscono informazioni sufficienti possono essere convertiti in questo errore.

Mappatura HTTP: errore interno del server 500

INVALID_ARGUMENT

Il client ha specificato un argomento non valido. Tieni presente che è diverso da FAILED_PRECONDITION. INVALID_ARGUMENT indica argomenti problematici a prescindere dallo stato del sistema (ad es. il nome file non valido).

Mappatura HTTP: richiesta 400 non valida

DEADLINE_EXCEEDED

La scadenza è scaduta prima del completamento dell'operazione. Per le operazioni che modificano lo stato del sistema, questo errore può essere restituito anche se l'operazione è stata completata correttamente. Ad esempio, una risposta riuscita da un server potrebbe essere stata ritardata abbastanza a lungo da scadere la scadenza.

Mappatura HTTP: timeout del gateway 504

NOT_FOUND

Non è stata trovata alcune entità richieste (ad es. file o directory).

Nota per gli sviluppatori di server: se una richiesta viene rifiutata per un'intera classe di utenti, ad esempio implementazione graduale delle funzionalità o lista consentita non documentata, NOT_FOUND potrebbe essere utilizzato. Se una richiesta viene rifiutata per alcuni utenti all'interno di una classe di utenti, ad esempio il controllo dell'accesso basato sugli utenti, è necessario utilizzare PERMISSION_DENIED.

Mappatura HTTP: 404 non trovato

ALREADY_EXISTS

L'entità che un client ha tentato di creare (ad es. file o directory) esiste già.

Mappatura HTTP: conflitto 409

PERMISSION_DENIED

Il chiamante non dispone dell'autorizzazione necessaria per eseguire l'operazione specificata. PERMISSION_DENIED non deve essere utilizzato per i rifiuti causati dall'esaurimento di alcune risorse (utilizza invece RESOURCE_EXHAUSTED per questi errori). PERMISSION_DENIED non deve essere utilizzato se non è possibile identificare il chiamante (utilizza UNAUTHENTICATED invece per questi errori). Questo codice di errore non implica la validità della richiesta oppure l'entità richiesta esiste o soddisfa altre precondizioni.

Mappatura HTTP: 403 Vietato

UNAUTHENTICATED

La richiesta non ha credenziali di autenticazione valide per l'operazione.

Mappatura HTTP: 401 Non autorizzato

RESOURCE_EXHAUSTED

Una risorsa è stata esaurita, forse una quota per utente o forse l'intero file system è esaurito.

Mappatura HTTP: troppe richieste 429

FAILED_PRECONDITION

L'operazione è stata rifiutata perché il sistema non è in uno stato richiesto per l'esecuzione dell'operazione. Ad esempio, la directory da eliminare non è vuota, un'operazione rmdir viene applicata a una directory non ecc.

Gli strumenti di implementazione dei servizi possono utilizzare le seguenti linee guida per decidere tra FAILED_PRECONDITION, ABORTED e UNAVAILABLE: (a) Utilizza UNAVAILABLE se il client può riprovare solo la chiamata in errore. (b) Utilizza ABORTED se il client deve riprovare a un livello superiore. Ad esempio, se un test e un set specificati dal client hanno esito negativo, il client deve riavviare una sequenza di lettura, modifica e scrittura. (c) Utilizza FAILED_PRECONDITION se il client non deve riprovare fino a quando lo stato del sistema non è stato esplicitamente risolto. Ad esempio, se un errore "rmdir" non va a buon fine perché la directory non è vuota, è necessario restituire FAILED_PRECONDITION perché il client non dovrebbe riprovare, a meno che i file non vengano eliminati dalla directory.

Mappatura HTTP: richiesta 400 non valida

ABORTED

L'operazione è stata interrotta, in genere a causa di un problema di contemporaneità come un errore di controllo del sequenziatore o un'interruzione della transazione.

Consulta le linee guida riportate sopra per decidere tra FAILED_PRECONDITION, ABORTED e UNAVAILABLE.

Mappatura HTTP: conflitto 409

OUT_OF_RANGE

L'operazione è stata tentata oltre l'intervallo valido. Ad esempio, ricerca o lettura di fine file.

A differenza di INVALID_ARGUMENT, questo errore indica un problema che potrebbe essere risolto se lo stato di sistema cambia. Ad esempio, un file system a 32 bit genererà INVALID_ARGUMENT se ti viene chiesto di leggere con un offset che non è compreso nell'intervallo [0,2^32-1], ma genererà OUT_OF_RANGE se ti viene chiesto di leggere da un offset oltre le dimensioni del file corrente.

C'è una leggera sovrapposizione tra FAILED_PRECONDITION e OUT_OF_RANGE. Consigliamo di utilizzare OUT_OF_RANGE (l'errore più specifico) quando si applica, in modo che i chiamanti che eseguono l'iterazione attraverso uno spazio possano facilmente cercare un errore OUT_OF_RANGE da rilevare al termine dell'operazione.

Mappatura HTTP: richiesta 400 non valida

UNIMPLEMENTED

L'operazione non è implementata o non è supportata/attivata in questo servizio.

Mappatura HTTP: 501 non implementata

INTERNAL

Errori interni. Ciò significa che alcune varianti non previste dal sistema sottostante sono state interrotte. Questo codice è riservato a errori gravi.

Mappatura HTTP: errore interno del server 500

UNAVAILABLE

Il servizio non è al momento disponibile. Questa è molto probabilmente una condizione temporanea, che può essere corretta ritentando l'esecuzione di un backoff. Tieni presente che non è sempre sicuro riprovare le operazioni non idempotenti.

Consulta le linee guida riportate sopra per decidere tra FAILED_PRECONDITION, ABORTED e UNAVAILABLE.

Mappatura HTTP: servizio 503 non disponibile

DATA_LOSS

Perdita o danneggiamento dei dati non recuperabili.

Mappatura HTTP: errore interno del server 500