Package google.rpc

Index

BadRequest

Décrit les cas de non-respect dans une requête client. Ce type d'erreur se concentre sur les aspects syntaxiques de la requête.

Champs
field_violations[]

FieldViolation

Décrit toutes les violations dans une requête client.

FieldViolation

Type de message utilisé pour décrire un seul champ de requête incorrect.

Champs
field

string

Chemin d'accès à un champ du corps de la requête. La valeur sera une séquence d'identifiants séparés par des points, qui identifient un champ de tampon de protocole.

Réfléchissez aux éléments suivants :

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;
}

Dans cet exemple, dans le fichier proto, field peut prendre l'une des valeurs suivantes :

  • full_name pour un cas de non-respect de la valeur full_name
  • email_addresses[1].email pour non-respect dans le champ email du premier message email_addresses
  • email_addresses[3].type[2] pour un cas de non-respect dans la deuxième valeur type dans le troisième message email_addresses.

En JSON, les mêmes valeurs sont représentées comme suit :

  • fullName pour un cas de non-respect de la valeur fullName
  • emailAddresses[1].email pour un non-respect dans le champ email du premier message emailAddresses
  • emailAddresses[3].type[2] pour un cas de non-respect dans la deuxième valeur type dans le troisième message emailAddresses.
description

string

Description de la raison pour laquelle l'élément de la requête est incorrect.
reason

string

Raison de l'erreur au niveau du champ. Il s'agit d'une valeur constante qui identifie la cause immédiate de l'erreur au niveau du champ. Il doit identifier de manière unique le type de FieldViolation dans le champ d'application de google.rpc.ErrorInfo.domain. Il doit comporter 63 caractères maximum et correspondre à l'expression régulière [A-Z][A-Z0-9_]+[A-Z0-9], qui représente UPPER_SNAKE_CASE.
localized_message

LocalizedMessage

Fournit un message d'erreur localisé pour les erreurs au niveau des champs, qui peut être renvoyé à l'utilisateur de l'API.

Code

Les codes d'erreur canoniques pour les API de gRPC.

Parfois, plusieurs codes d'erreur peuvent s'appliquer. Les services doivent renvoyer le code d'erreur le plus spécifique qui s'applique. Par exemple, préférez OUT_OF_RANGE à FAILED_PRECONDITION si les deux codes s'appliquent. De même, préférez NOT_FOUND ou ALREADY_EXISTS à FAILED_PRECONDITION.

Enums
OK

Pas une erreur, affiché en cas de réussite.

Mise en correspondance HTTP : 200 OK
CANCELLED

L'opération a été annulée, généralement par l'appelant.

Mise en correspondance HTTP : 499 Le client a fermé la requête
UNKNOWN

Erreur inconnue. Par exemple, cette erreur peut s'afficher lorsqu'une valeur Status reçue d'un autre espace d'adressage appartient à un espace d'erreur inconnu dans cet espace d'adressage. De plus, les erreurs des API qui ne renvoient pas suffisamment d'informations relatives aux erreurs peuvent être converties dans cette erreur.

Mise en correspondance HTTP : 500 Erreur de serveur interne
INVALID_ARGUMENT

Le client a spécifié un argument non valide. Notez que cette erreur diffère de FAILED_PRECONDITION. INVALID_ARGUMENT indique les arguments problématiques, quel que soit l'état du système (par exemple, un nom de fichier incorrect).

Mise en correspondance HTTP : 400 Requête incorrecte
DEADLINE_EXCEEDED

Le délai a expiré avant que l'opération puisse se terminer. Pour les opérations qui modifient l'état du système, cette erreur peut être affichée même si l'opération s'est terminée avec succès. Par exemple, une réponse réussie d'un serveur aurait pu être retardée suffisamment longtemps pour que le délai expire.

Mappage HTTP : 504 Passerelle hors délai
NOT_FOUND

Une entité demandée (fichier ou répertoire, par exemple) est introuvable.

Remarque pour les développeurs de serveurs : NOT_FOUND peut être utilisé si une requête est refusée pour toute une classe d'utilisateurs, telle que le déploiement progressif d'une fonctionnalité ou une liste d'autorisation non documentée. Si une requête est refusée pour certains utilisateurs appartenant à une classe d'utilisateurs, telle que le contrôle des accès basé sur l'utilisateur, PERMISSION_DENIED doit être utilisé.

Mise en correspondance HTTP : 404 Page introuvable
ALREADY_EXISTS

L'entité qu'un client a tenté de créer (par exemple, un fichier ou un répertoire) existe déjà.

Mise en correspondance HTTP : 409 Conflit
PERMISSION_DENIED

L'appelant n'a pas l'autorisation d'exécuter l'opération spécifiée. PERMISSION_DENIED ne doit pas être utilisé pour les rejets causés par l'épuisement d'une ressource (utilisez plutôt RESOURCE_EXHAUSTED pour ces erreurs). PERMISSION_DENIED ne doit pas être utilisé si l'appelant ne peut pas être identifié (utilisez plutôt UNAUTHENTICATED pour ces erreurs). Ce code d'erreur n'implique pas que la requête soit valide ni que l'entité demandée existe ou qu'elle répond à d'autres pré-requis.

Mise en correspondance HTTP : 403 Accès interdit
UNAUTHENTICATED

La requête ne dispose pas d'identifiants d'authentification valides pour l'opération.

Mise en correspondance HTTP : 401 Accès non autorisé
RESOURCE_EXHAUSTED

Certaines ressources ont été épuisées ; par exemple, un quota par utilisateur a été atteint ou le système de fichiers dans son intégralité manque d'espace.

Mise en correspondance HTTP : 429 Requêtes trop nombreuses
FAILED_PRECONDITION

L'opération a été rejetée car le système n'est pas dans un état requis pour exécuter l'opération. Par exemple, le répertoire à supprimer n'est pas vide, une opération rmdir est appliquée à un emplacement qui n'est pas un répertoire, etc.

Les développeurs de services peuvent suivre les instructions suivantes pour choisir entre FAILED_PRECONDITION, ABORTED et UNAVAILABLE : (a) Utilisez UNAVAILABLE si le client ne peut relancer que l'appel ayant échoué. (b) Utilisez ABORTED si le client doit effectuer une nouvelle tentative à un niveau supérieur (par exemple, lorsqu'un test-and-set spécifié par le client échoue, indiquant que le client doit redémarrer une séquence lecture-modification-écriture). (c) Utilisez FAILED_PRECONDITION si le client ne doit pas effectuer de nouvelle tentative tant que l'état du système n'a pas été explicitement corrigé. Par exemple, si un "rmdir" échoue parce que le répertoire n'est pas vide, FAILED_PRECONDITION doit être affiché car le client ne doit pas réessayer sauf si les fichiers sont supprimés du répertoire.

Mise en correspondance HTTP : 400 Requête incorrecte
ABORTED

L'opération a été abandonnée, généralement en raison d'un problème de simultanéité, tel qu'un échec de vérification du séquenceur ou un abandon de transaction.

Consultez les instructions ci-dessus pour choisir entre FAILED_PRECONDITION, ABORTED et UNAVAILABLE.

Mise en correspondance HTTP : 409 Conflit
OUT_OF_RANGE

L'opération a été tentée au-delà de la plage valide. Par exemple, rechercher ou lire après la fin du fichier.

Contrairement à INVALID_ARGUMENT, cette erreur indique un problème pouvant être résolu si l'état du système change. Par exemple, un système de fichiers 32 bits générera INVALID_ARGUMENT s'il est invité à lire avec un décalage qui n'est pas compris dans la plage [0,2 ^ 32-1], mais générera OUT_OF_RANGE s'il est invité à lire avec un décalage qui dépasse la taille du fichier actuel.

Il existe des cas où FAILED_PRECONDITION et OUT_OF_RANGE se chevauchent. Nous vous recommandons d'utiliser OUT_OF_RANGE (l'erreur la plus spécifique) lorsque celle-ci s'applique afin que les appelants qui itèrent dans un espace puissent facilement rechercher une erreur OUT_OF_RANGE pour détecter le moment où ils ont terminé.

Mise en correspondance HTTP : 400 Requête incorrecte
UNIMPLEMENTED

L'opération n'est pas implémentée ou n'est pas prise en charge/activée dans ce service.

Mise en correspondance HTTP : 501 Non implémenté
INTERNAL

Erreurs internes. Cela signifie que certains invariants attendus par le système sous-jacent n'ont pas été respectés. Ce code d'erreur est réservé aux erreurs graves.

Mise en correspondance HTTP : 500 Erreur de serveur interne
UNAVAILABLE

Le service est actuellement indisponible. Il s'agit probablement d'une condition temporaire qui peut être corrigée en réessayant après avoir laissé passer un intervalle entre les tentatives. Notez qu'il n'est pas toujours sûr de relancer des opérations non idempotentes.

Consultez les instructions ci-dessus pour choisir entre FAILED_PRECONDITION, ABORTED et UNAVAILABLE.

Mise en correspondance HTTP : 503 Service non disponible
DATA_LOSS

Perte ou corruption de données irrécupérable.

Mise en correspondance HTTP : 500 Erreur de serveur interne

Information sur l'erreur

Décrit la cause de l'erreur avec des détails structurés.

Voici un exemple d'erreur qui se produit lorsque vous contactez l'API "pubsub.googleapis.com" alors qu'elle n'est pas activée :

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

Cette réponse indique que l'API pubsub.googleapis.com n'est pas activée.

Voici un exemple d'erreur renvoyée lorsque vous essayez de créer une instance Spanner dans une région où le produit est en rupture de stock :

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

string

Raison de l'erreur. Il s'agit d'une valeur constante qui identifie la cause immédiate de l'erreur. Les raisons d'erreur sont uniques dans un domaine d'erreurs spécifique. Cette valeur ne doit pas comporter plus de 63 caractères et doit correspondre à l'expression régulière [A-Z][A-Z0-9_]+[A-Z0-9], qui représente UPPER_SNAKE_CASE.
domain

string

Regroupement logique auquel appartient la "raison". Le domaine d'erreur est généralement le nom de service enregistré de l'outil ou du produit qui génère l'erreur. Exemple : "pubsub.googleapis.com". Si l'erreur est générée par une infrastructure commune, le domaine d'erreur doit être une valeur unique au niveau mondial qui identifie l'infrastructure. Pour l'infrastructure des API Google, le domaine d'erreur est "googleapis.com".
metadata

map<string, string>

Informations structurées supplémentaires sur cette erreur.

Les clés doivent correspondre à une expression régulière de [a-z][a-zA-Z0-9-_]+, mais doivent idéalement être en lowerCamelCase. De plus, ils ne doivent pas dépasser 64 caractères. Lorsque vous identifiez la valeur actuelle d'une limite dépassée, les unités doivent figurer dans la clé, et non dans la valeur. Par exemple, au lieu de {"instanceLimit": "100/request"}, la réponse devrait être {"instanceLimitPerRequest": "100"} si le client dépasse le nombre d'instances pouvant être créées dans une seule requête (par lot).

Aide

Fournit des liens vers la documentation ou pour effectuer une action hors bande.

Par exemple, si une vérification de quota a échoué avec une erreur indiquant que le projet appelant n'a pas activé le service auquel il accède, cela peut contenir une URL pointant directement vers le bon endroit dans la console de développement pour activer le bit.

Champs

LocalizedMessage

Fournit un message d'erreur localisé qui peut être renvoyé à l'utilisateur et qui peut être associé à une erreur RPC.

Champs
locale

string

Paramètres régionaux utilisés conformément à la spécification définie sur https://www.rfc-editor.org/rfc/bcp/bcp47.txt. Exemples : "en-US", "fr-CH", "es-MX"
message

string

Message d'erreur localisé dans les paramètres régionaux ci-dessus.

PreconditionFailure

Décrit les conditions préalables qui n'ont pas été remplies.

Par exemple, si un RPC a échoué parce qu'il nécessitait l'acceptation des conditions d'utilisation, il peut lister la violation des conditions d'utilisation dans le message PreconditionFailure.

Champs
violations[]

Violation

Décrit tous les cas de non-respect des conditions préalables.

Infraction

Type de message utilisé pour décrire un seul échec de précondition.

Champs
type

string

Type de PreconditionFailure. Nous vous recommandons d'utiliser un type d'énumération spécifique au service pour définir les sujets de non-respect des conditions préalables acceptés. Par exemple, "TOS" pour "Non-respect des conditions d'utilisation".
subject

string

Sujet, par rapport au type, qui a échoué. Par exemple, "google.com/cloud" par rapport au type "TOS" indiquerait les conditions d'utilisation auxquelles il est fait référence.
description

string

Description de l'échec de la condition préalable. Les développeurs peuvent utiliser cette description pour comprendre comment résoudre l'échec.

Par exemple : "Conditions d'utilisation non acceptées".

QuotaFailure

Décrit comment une vérification de quota a échoué.

Par exemple, si une limite quotidienne a été dépassée pour le projet appelant, un service peut répondre avec un détail QuotaFailure contenant l'ID du projet et la description de la limite de quota qui a été dépassée. Si le projet appelant n'a pas activé le service dans la console de développement, un service peut répondre avec l'ID du projet et définir service_disabled sur "true".

Consultez également les types RetryInfo et Help pour en savoir plus sur la gestion des échecs de quota.

Champs
violations[]

Violation

Décrit toutes les violations de quota.

Infraction

Type de message utilisé pour décrire un seul cas de non-respect du quota. (par exemple, un quota quotidien ou personnalisé qui a été dépassé).

Champs
subject

string

Sujet pour lequel la vérification du quota a échoué. Par exemple, "clientip:" ou "project:".
description

string

Description de l'échec de la vérification du quota. Les clients peuvent utiliser cette description pour en savoir plus sur la configuration des quotas dans la documentation publique du service ou trouver la limite de quota appropriée à ajuster dans la console de développement.

Par exemple : "Service désactivé" ou "Limite quotidienne pour les opérations de lecture dépassée".
api_service

string

Service API à partir duquel provient QuotaFailure.Violation. Dans certains cas, les problèmes de quota proviennent d'un service d'API autre que celui qui a été appelé. En d'autres termes, une dépendance du service d'API appelé peut être à l'origine de l'erreur QuotaFailure. Dans ce cas, le nom du service d'API de dépendance est indiqué dans ce champ.

Par exemple, si l'API appelée est l'API Kubernetes Engine (container.googleapis.com) et qu'un dépassement de quota se produit dans l'API Kubernetes Engine elle-même, ce champ sera "container.googleapis.com". En revanche, si le dépassement de quota se produit lorsque l'API Kubernetes Engine crée des VM dans l'API Compute Engine (compute.googleapis.com), ce champ sera "compute.googleapis.com".
quota_metric

string

Métrique du quota enfreint. Une métrique de quota est un compteur nommé permettant de mesurer l'utilisation, comme les requêtes API ou les processeurs. Lorsqu'une activité se produit dans un service, comme l'allocation de machines virtuelles, une ou plusieurs métriques de quota peuvent être affectées.

Par exemple, "compute.googleapis.com/cpus_per_vm_family", "storage.googleapis.com/internet_egress_bandwidth".
quota_id

string

ID du quota enfreint. Également appelé "nom de la limite", il s'agit de l'identifiant unique d'un quota dans le contexte d'un service d'API.

Par exemple, "CPUS-PER-VM-FAMILY-per-project-region".
quota_dimensions

map<string, string>

Dimensions du quota enfreint. Chaque quota non global est appliqué à un ensemble de dimensions. Alors que la métrique de quota définit ce qu'il faut comptabiliser, les dimensions spécifient les aspects pour lesquels le compteur doit être incrémenté.

Par exemple, le quota "Processeurs par région et par famille de VM" applique une limite à la métrique "compute.googleapis.com/cpus_per_vm_family" sur les dimensions "region" et "vm_family". Si le non-respect s'est produit dans la région "us-central1" et pour la famille de VM "n1", les quota_dimensions seraient les suivants :

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

Lorsqu'un quota est appliqué au niveau mondial, quota_dimensions est toujours vide.
quota_value

int64

Valeur du quota appliqué au moment de l'QuotaFailure.

Par exemple, si la valeur du quota appliqué au moment de l'QuotaFailure sur le nombre de processeurs est "10", la valeur de ce champ reflète cette quantité.
future_quota_value

int64

La nouvelle valeur de quota déployée au moment de l'infraction. Une fois le déploiement terminé, cette valeur sera appliquée à la place de quota_value. Si aucun déploiement n'est en cours au moment de l'infraction, ce champ n'est pas défini.

Par exemple, si au moment de l'infraction, un déploiement est en cours pour modifier le quota de nombre de processeurs de 10 à 20, la valeur de ce champ sera de 20.

RequestInfo

Contient des métadonnées sur la requête que les clients peuvent joindre lorsqu'ils signalent un bug ou fournissent d'autres types de commentaires.

Champs
request_id

string

Chaîne opaque qui ne doit être interprétée que par le service qui la génère. Par exemple, il peut être utilisé pour identifier les requêtes dans les journaux du service.
serving_data

string

Toutes les données utilisées pour traiter cette demande. Par exemple, une trace de pile chiffrée qui peut être renvoyée au fournisseur de services pour le débogage.

ResourceInfo

Décrit la ressource à laquelle l'utilisateur tente d'accéder.

Champs
resource_type

string

Nom du type de ressource auquel l'utilisateur accède (par exemple, "table SQL", "bucket Cloud Storage", "fichier" ou "agenda Google") ou URL du type de ressource (par exemple, "type.googleapis.com/google.pubsub.v1.Topic").
resource_name

string

Nom de la ressource consultée. Par exemple, le nom d'un agenda partagé : "example.com_4fghdhgsrgh@group.calendar.google.com", si l'erreur actuelle est google.rpc.Code.PERMISSION_DENIED.
owner

string

Propriétaire de la ressource (facultatif). Par exemple, "user:" ou "project:".
description

string

Décrit l'erreur rencontrée lors de l'accès à cette ressource. Par exemple, la mise à jour d'un projet Cloud peut nécessiter l'autorisation writer sur le projet de la console pour les développeurs.

RetryInfo

Décrit quand les clients peuvent réessayer une requête ayant échoué. Les clients peuvent ignorer la recommandation ici ou réessayer lorsque ces informations sont manquantes dans les réponses d'erreur.

Il est toujours recommandé aux clients d'utiliser un intervalle exponentiel entre les tentatives.

Les clients doivent attendre retry_delay avant de réessayer après avoir reçu la réponse d'erreur. Si les nouvelles tentatives de requête échouent également, les clients doivent utiliser un schéma d'intervalle exponentiel entre les tentatives pour augmenter progressivement le délai entre les tentatives en fonction de retry_delay, jusqu'à ce qu'un nombre maximal de tentatives ou un délai maximal entre les tentatives soient atteints.

Champs
retry_delay

Duration

Les clients doivent attendre au moins cette durée avant de réessayer la même requête.

État

Le type Status définit un modèle d'erreur logique adapté aux différents environnements de programmation, y compris les API REST et RPC. Il est utilisé par le protocole gRPC. Chaque message Status contient trois éléments de données : un code d'erreur, un message d'erreur et les détails de l'erreur.

Pour en savoir plus sur ce modèle d'erreur et sur son utilisation, consultez le Guide de conception d'API.

Champs
code

int32

Code d'état, qui doit être une valeur d'énumération de google.rpc.Code.
message

string

Message d'erreur destiné au développeur, qui doit être en anglais. Tout message d'erreur destiné aux utilisateurs doit être localisé et envoyé dans le champ google.rpc.Status.details, ou localisé par le client.
details[]

Any

Liste de messages comportant les détails de l'erreur. Il existe un ensemble commun de types de message utilisable par les API.