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 è errato.
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 questo valore è diverso 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
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 corretta da un server potrebbe essere stata ritardata abbastanza a lungo da far scadere il termine.

Mappatura HTTP: timeout del gateway (504)
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 il lancio graduale di funzionalità o 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à.

Mapping HTTP: 409 Conflict
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 è nello stato richiesto per l'esecuzione dell'operazione. Ad esempio, la directory da eliminare non è vuota, un'operazione rmdir viene applicata a un elemento non di tipo 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
ABORTED

L'operazione è stata interrotta, in genere a causa di un problema di concorrenza, ad esempio un controllo del sequencer non riuscito o un'interruzione della transazione.

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

Mapping HTTP: 409 Conflict
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 potrebbe essere risolto se lo stato del sistema cambia. Ad esempio, un file system a 32 bit genererà INVALID_ARGUMENT se viene richiesto di leggere a un offset non compreso nell'intervallo [0,2^32-1], ma genererà OUT_OF_RANGE se viene richiesto 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
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

ErrorInfo

Descrive la causa dell'errore con dettagli strutturati.

Esempio di errore durante il contatto con l'API "pubsub.googleapis.com" quando non è abilitata:

{ "reason": "API_DISABLED"
  "domain": "googleapis.com"
  "metadata": {
    "resource": "projects/123",
    "service": "pubsub.googleapis.com"
  }
}

Questa risposta indica che l'API pubsub.googleapis.com non è abilitata.

Esempio di errore restituito quando si tenta di creare un'istanza Spanner in una regione esaurita:

{ "reason": "STOCKOUT"
  "domain": "spanner.googleapis.com",
  "metadata": {
    "availableRegions": "us-central1,us-east2"
  }
}
Campi
reason

string

Il motivo dell'errore. Si tratta di un valore costante che identifica la causa prossima dell'errore. I motivi dell'errore sono univoci all'interno di un determinato dominio di errori. 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.
domain

string

Il raggruppamento logico a cui appartiene il "motivo". Il dominio di errore è in genere il nome del servizio registrato dello strumento o del prodotto che genera l'errore. Esempio: "pubsub.googleapis.com". Se l'errore viene generato da un'infrastruttura comune, il dominio di errore deve essere un valore univoco a livello globale che identifica l'infrastruttura. Per l'infrastruttura API di Google, il dominio di errore è "googleapis.com".
metadata

map<string, string>

Dettagli strutturati aggiuntivi su questo errore.

Le chiavi devono corrispondere a un'espressione regolare di [a-z][a-zA-Z0-9-_]+, ma idealmente devono essere in formato lowerCamelCase. Inoltre, devono contenere al massimo 64 caratteri. Quando identifichi il valore corrente di un limite superato, le unità devono essere contenute nella chiave, non nel valore. Ad esempio, anziché {"instanceLimit": "100/request"}, deve essere restituito come {"instanceLimitPerRequest": "100"} se il client supera il numero di istanze che possono essere create in una singola richiesta (batch).

Guida

Fornisce link alla documentazione o per eseguire un'azione fuori banda.

Ad esempio, se un controllo della quota non è riuscito con un errore che indica che il progetto chiamante non ha attivato il servizio a cui è stato eseguito l'accesso, questo può contenere un URL che rimanda direttamente alla posizione corretta nella console per gli sviluppatori per attivare il bit.

Campi

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.

PreconditionFailure

Descrive quali precondizioni non sono state soddisfatte.

Ad esempio, se una RPC non è riuscita perché richiedeva l'accettazione dei Termini di servizio, potrebbe elencare la violazione dei termini di servizio nel messaggio PreconditionFailure.

Campi
violations[]

Violation

Descrive tutte le violazioni delle precondizioni.

Violazione

Un tipo di messaggio utilizzato per descrivere un singolo errore di precondizione.

Campi
type

string

Il tipo di PreconditionFailure. Ti consigliamo di utilizzare un tipo di enumerazione specifico del servizio per definire i soggetti di violazione delle precondizioni supportati. Ad esempio, "TOS" per "Violazione dei Termini di servizio".
subject

string

Il soggetto, relativo al tipo, per cui l'operazione non è riuscita. Ad esempio, "google.com/cloud" rispetto al tipo "TOS" indicherebbe a quali termini di servizio si fa riferimento.
description

string

Una descrizione del motivo per cui la precondizione non è riuscita. Gli sviluppatori possono utilizzare questa descrizione per capire come risolvere l'errore.

Ad esempio: "Termini di servizio non accettati".

QuotaFailure

Descrive il motivo per cui un controllo della quota non è riuscito.

Ad esempio, se un limite giornaliero è stato superato per il progetto chiamante, un servizio potrebbe rispondere con un dettaglio QuotaFailure contenente l'ID progetto e la descrizione del limite di quota superato. Se il progetto chiamante non ha attivato il servizio nella console per gli sviluppatori, un servizio potrebbe rispondere con l'ID progetto e impostare service_disabled su true.

Consulta anche i tipi RetryInfo e Help per altri dettagli sulla gestione di un errore di quota.

Campi
violations[]

Violation

Descrive tutte le violazioni delle quote.

Violazione

Un tipo di messaggio utilizzato per descrivere una singola violazione della quota. Ad esempio, una quota giornaliera o una quota personalizzata che è stata superata.

Campi
subject

string

Il soggetto per cui il controllo della quota non è riuscito. Ad esempio, "clientip:" o "project:".
description

string

Una descrizione del motivo per cui il controllo della quota non è riuscito. I clienti possono utilizzare questa descrizione per scoprire di più sulla configurazione delle quote nella documentazione pubblica del servizio o trovare il limite di quota pertinente da modificare tramite la console per gli sviluppatori.

Ad esempio: "Servizio disattivato" o "Limite giornaliero per le operazioni di lettura superato".
api_service

string

Il servizio API da cui ha origine QuotaFailure.Violation. In alcuni casi, i problemi relativi alla quota hanno origine da un servizio API diverso da quello chiamato. In altre parole, una dipendenza del servizio API chiamato potrebbe essere la causa di QuotaFailure e questo campo conterrebbe il nome del servizio API di dipendenza.

Ad esempio, se l'API chiamata è l'API Kubernetes Engine (container.googleapis.com) e si verifica una violazione della quota nell'API Kubernetes Engine stessa, questo campo sarà "container.googleapis.com". D'altra parte, se la violazione della quota si verifica quando l'API Kubernetes Engine crea VM nell'API Compute Engine (compute.googleapis.com), questo campo sarà "compute.googleapis.com".
quota_metric

string

La metrica della quota violata. Una metrica di quota è un contatore denominato per misurare l'utilizzo, ad esempio le richieste API o le CPU. Quando si verifica un'attività in un servizio, ad esempio l'allocazione di una macchina virtuale, una o più metriche di quota potrebbero essere interessate.

Ad esempio, "compute.googleapis.com/cpus_per_vm_family", "storage.googleapis.com/internet_egress_bandwidth".
quota_id

string

L'ID della quota violata. Noto anche come "nome limite", è l'identificatore univoco di una quota nel contesto di un servizio API.

Ad esempio, "CPUS-PER-VM-FAMILY-per-project-region".
quota_dimensions

map<string, string>

Le dimensioni della quota violata. Ogni quota non globale viene applicata a un insieme di dimensioni. Mentre la metrica quota definisce cosa conteggiare, le dimensioni specificano per quali aspetti deve essere incrementato il contatore.

Ad esempio, la quota "CPU per regione per famiglia di VM" impone un limite alla metrica "compute.googleapis.com/cpus_per_vm_family" per le dimensioni "region" e "vm_family". Se la violazione si è verificata nella regione "us-central1" e per la famiglia di VM "n1", quota_dimensions sarebbe:

{ "region": "us-central1", "vm_family": "n1", }

Quando una quota viene applicata a livello globale, quota_dimensions è sempre vuoto.
quota_value

int64

Il valore della quota applicata al momento del QuotaFailure.

Ad esempio, se il valore della quota applicata al momento di QuotaFailure sul numero di CPU è "10", il valore di questo campo rifletterà questa quantità.
future_quota_value

int64

Il nuovo valore della quota in fase di implementazione al momento della violazione. Al termine dell'implementazione, questo valore verrà applicato al posto di quota_value. Se al momento della violazione non è in corso alcuna implementazione, questo campo non viene impostato.

Ad esempio, se al momento della violazione è in corso un'implementazione che modifica la quota del numero di CPU da 10 a 20, 20 sarà il valore di questo campo.

RequestInfo

Contiene metadati sulla richiesta che i client possono allegare quando segnalano un bug o forniscono altri tipi di feedback.

Campi
request_id

string

Una stringa opaca che deve essere interpretata solo dal servizio che la genera. Ad esempio, può essere utilizzato per identificare le richieste nei log del servizio.
serving_data

string

Qualsiasi dato utilizzato per soddisfare questa richiesta. Ad esempio, una traccia dello stack criptata che può essere inviata al fornitore di servizi per il debug.

ResourceInfo

Descrive la risorsa a cui viene eseguito l'accesso.

Campi
resource_type

string

Un nome per il tipo di risorsa a cui si accede, ad esempio "tabella SQL", "bucket Cloud Storage", "file", "Google Calendar"; o l'URL del tipo di risorsa: ad esempio "type.googleapis.com/google.pubsub.v1.Topic".
resource_name

string

Il nome della risorsa a cui viene eseguito l'accesso. Ad esempio, un nome di calendario condiviso: "example.com_4fghdhgsrgh@group.calendar.google.com", se l'errore attuale è google.rpc.Code.PERMISSION_DENIED.
owner

string

(Facoltativo) Il proprietario della risorsa. Ad esempio, "user:" o "project:".
description

string

Descrive l'errore riscontrato durante l'accesso a questa risorsa. Ad esempio, l'aggiornamento di un progetto cloud potrebbe richiedere l'autorizzazione writer sul progetto Developer Console.

RetryInfo

Descrive quando i client possono riprovare una richiesta non riuscita. I client potrebbero ignorare il consiglio qui o riprovare quando queste informazioni non sono presenti nelle risposte di errore.

È sempre consigliabile che i client utilizzino il backoff esponenziale quando riprovano.

I client devono attendere che siano trascorsi retry_delay dall'invio della risposta di errore prima di riprovare. Se anche i tentativi di ripetizione delle richieste non vanno a buon fine, i client devono utilizzare uno schema di backoff esponenziale per aumentare gradualmente il ritardo tra i tentativi in base a retry_delay, finché non viene raggiunto un numero massimo di tentativi o un limite massimo di ritardo tra i tentativi.

Campi
retry_delay

Duration

I client devono attendere almeno questo periodo di tempo prima di riprovare a inviare la stessa richiesta.

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. Ciascun messaggio Status contiene tre tipi di dati: codice di errore, messaggio di errore e dettagli dell'errore.

Per ulteriori informazioni su questo modello di errore e su come gestirlo, consulta la 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 agli utenti deve essere localizzato e inviato nel campo google.rpc.Status.details o localizzato dal client.
details[]

Any

Un elenco di messaggi contenenti i dettagli dell'errore. Esiste un insieme comune di tipi di messaggi da utilizzare per le API.