Package google.rpc

Indice

BadRequest

Descrive le violazioni in una richiesta del client. Questo tipo di errore si concentra sugli aspetti sintattici della richiesta.

Campi
field_violations[]

FieldViolation

Descrive tutte le violazioni in una richiesta del client.

FieldViolation

Un tipo di messaggio utilizzato per descrivere un singolo campo di richiesta errata.

Campi
field

string

Un percorso che porta a un campo nel corpo della richiesta. Il valore sarà una sequenza di identificatori separati da punti che identificano un campo del buffer del protocollo.

Considera quanto segue:

message CreateContactRequest {
  message EmailAddress {
    enum Type {
      TYPE_UNSPECIFIED = 0;
      HOME = 1;
      WORK = 2;
    }

    optional string email = 1;
    repeated EmailType type = 2;
  }

  string full_name = 1;
  repeated EmailAddress email_addresses = 2;
}

In questo esempio, in proto field potrebbe assumere uno dei seguenti valori:

  • full_name per una violazione nel valore full_name
  • email_addresses[1].email per una violazione nel campo email del primo messaggio email_addresses
  • email_addresses[3].type[2] per una violazione nel secondo valore type nel terzo messaggio email_addresses.

In JSON, gli stessi valori sono rappresentati come segue:

  • fullName per una violazione nel valore fullName
  • emailAddresses[1].email per una violazione nel campo email del primo messaggio emailAddresses
  • emailAddresses[3].type[2] per una violazione nel secondo valore type nel terzo messaggio emailAddresses.
description

string

Una descrizione del motivo per cui l'elemento della richiesta non è valido.
reason

string

Il motivo dell'errore a livello di campo. Si tratta di un valore costante che identifica la causa prossima dell'errore a livello di campo. Deve identificare in modo univoco il tipo di FieldViolation nell'ambito di google.rpc.ErrorInfo.domain. Deve contenere al massimo 63 caratteri e corrispondere a un'espressione regolare di [A-Z][A-Z0-9_]+[A-Z0-9], che rappresenta UPPER_SNAKE_CASE.
localized_message

LocalizedMessage

Fornisce un messaggio di errore localizzato per gli errori a livello di campo che è sicuro restituire al consumer dell'API.

Codice

I codici di errore canonici per le API gRPC.

A volte possono essere applicati più codici di errore. I servizi devono restituire il codice di errore più specifico applicabile. Ad esempio, preferisci OUT_OF_RANGE a FAILED_PRECONDITION se entrambi i codici sono applicabili. Allo stesso modo, preferisci NOT_FOUND o ALREADY_EXISTS a FAILED_PRECONDITION.

Enum
OK

Non è un errore; viene restituito in caso di esito positivo.

Mapping HTTP: 200 OK
CANCELLED

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

Mappatura HTTP: 499 Client Closed Request
UNKNOWN

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

Mapping HTTP: 500 Internal Server Error
INVALID_ARGUMENT

Il client ha specificato un argomento non valido. Tieni presente che questa operazione è diversa da FAILED_PRECONDITION. INVALID_ARGUMENT indica argomenti problematici indipendentemente dallo stato del sistema (ad es. un nome file non valido).

Mapping HTTP: 400 Bad Request (Richiesta non valida)
DEADLINE_EXCEEDED

La scadenza è terminata prima che l'operazione potesse essere completata. 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 far scadere il termine.

Mappatura HTTP: 504 Gateway Timeout
NOT_FOUND

Impossibile trovare alcune entità richieste (ad es. file o directory).

Nota per gli sviluppatori di server: se una richiesta viene negata per un'intera classe di utenti, ad esempio per il lancio graduale di funzionalità o per una lista consentita non documentata, è possibile utilizzare NOT_FOUND. Se una richiesta viene negata per alcuni utenti all'interno di una classe di utenti, ad esempio controllo dell'accesso basato sull'utente, è necessario utilizzare PERMISSION_DENIED.

Mappatura HTTP: 404 Not Found
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 per eseguire l'operazione specificata. PERMISSION_DENIED non deve essere utilizzato per i rifiuti causati dall'esaurimento di alcune risorse (utilizza RESOURCE_EXHAUSTED per questi errori). PERMISSION_DENIED non deve essere utilizzato se il chiamante non può essere identificato (utilizza UNAUTHENTICATED per questi errori). Questo codice di errore non implica che la richiesta sia valida o che l'entità richiesta esista o soddisfi altre precondizioni.

Mappatura HTTP: 403 accesso negato
UNAUTHENTICATED

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

Mappatura HTTP: 401 Non autorizzato
RESOURCE_EXHAUSTED

Alcune risorse sono esaurite, ad esempio una quota per utente o l'intero file system è esaurito.

Mappatura HTTP: 429 Too Many Requests
FAILED_PRECONDITION

L'operazione è stata rifiutata perché il sistema non si trova nello stato richiesto per l'esecuzione dell'operazione. Ad esempio, la directory da eliminare non è vuota, un'operazione rmdir viene applicata a un elemento che non è una directory e così via.

Gli implementatori di 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 non riuscita. (b) Utilizza ABORTED se il client deve riprovare a un livello superiore. Ad esempio, quando un test-and-set specificato dal client non riesce, indicando che il client deve riavviare una sequenza di lettura-modifica-scrittura. (c) Utilizza FAILED_PRECONDITION se il client non deve riprovare finché lo stato del sistema non è stato corretto in modo esplicito. Ad esempio, se un comando "rmdir" non va a buon fine perché la directory non è vuota, FAILED_PRECONDITION deve essere restituito perché il client non deve riprovare a meno che i file non vengano eliminati dalla directory.

Mapping HTTP: 400 Bad Request (Richiesta non valida)
ABORTED

L'operazione è stata interrotta, in genere a causa di un problema di concorrenza, ad esempio un errore di controllo del sequencer 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, cercare o leggere la fine del file.

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

Esiste una sovrapposizione piuttosto ampia tra FAILED_PRECONDITION e OUT_OF_RANGE. Ti consigliamo di utilizzare OUT_OF_RANGE (l'errore più specifico) quando si applica, in modo che i chiamanti che scorrono uno spazio possano cercare facilmente un errore OUT_OF_RANGE per rilevare quando hanno terminato.

Mapping HTTP: 400 Bad Request (Richiesta non valida)
UNIMPLEMENTED

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

Mappatura HTTP: 501 Not Implemented
INTERNAL

Errori interni. Ciò significa che alcuni invarianti previsti dal sistema sottostante sono stati violati. Questo codice di errore è riservato agli errori gravi.

Mapping HTTP: 500 Internal Server Error
UNAVAILABLE

Il servizio non è al momento disponibile. Si tratta molto probabilmente di una condizione temporanea, che può essere corretta riprovando con 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: 503 Servizio non disponibile
DATA_LOSS

Perdita o danneggiamento dei dati non recuperabili.

Mapping HTTP: 500 Internal Server Error

LocalizedMessage

Fornisce un messaggio di errore localizzato che può essere restituito all'utente e che può essere allegato a un errore RPC.

Campi
locale

string

Le impostazioni internazionali utilizzate seguono la specifica definita all'indirizzo https://www.rfc-editor.org/rfc/bcp/bcp47.txt. Esempi: "en-US", "fr-CH", "es-MX"
message

string

Il messaggio di errore localizzato nella lingua indicata sopra.

Stato

Il tipo Status definisce un modello di errore logico adatto a diversi ambienti di programmazione, tra cui API REST e API RPC. Viene utilizzato da gRPC. Ogni messaggio Status contiene tre elementi di dati: codice di errore, messaggio di errore e dettagli dell'errore.

Puoi scoprire di più su questo modello di errore e su come utilizzarlo nella guida alla progettazione delle API.

Campi
code

int32

Il codice di stato, che deve essere un valore enum di google.rpc.Code.
message

string

Un messaggio di errore rivolto agli sviluppatori, che deve essere in inglese. Qualsiasi messaggio di errore rivolto all'utente deve essere localizzato e inviato nel campo google.rpc.Status.details o localizzato dal client.
details[]

Any

Un elenco di messaggi che contengono i dettagli dell'errore. Esiste un insieme comune di tipi di messaggi che le API possono utilizzare.