Package google.rpc

Índice

BadRequest

Describe las infracciones en una solicitud del cliente. Este tipo de error se enfoca en los aspectos sintácticos de la solicitud.

Campos
field_violations[]

FieldViolation

Describe todos los incumplimientos en una solicitud del cliente.

FieldViolation

Es un tipo de mensaje que se usa para describir un solo campo de solicitud incorrecta.

Campos
field

string

Es una ruta de acceso que lleva a un campo en el cuerpo de la solicitud. El valor será una secuencia de identificadores separados por puntos que identifican un campo de búfer de protocolo.

Ten en cuenta lo siguiente:

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

En este ejemplo, en el proto field podría tomar uno de los siguientes valores:

  • full_name para un incumplimiento en el valor de full_name
  • email_addresses[1].email para un incumplimiento en el campo email del primer mensaje email_addresses
  • email_addresses[3].type[2] por un incumplimiento en el segundo valor de type en el tercer mensaje de email_addresses

En JSON, los mismos valores se representan de la siguiente manera:

  • fullName para un incumplimiento en el valor de fullName
  • emailAddresses[1].email para un incumplimiento en el campo email del primer mensaje emailAddresses
  • emailAddresses[3].type[2] por un incumplimiento en el segundo valor de type en el tercer mensaje de emailAddresses
description

string

Es una descripción del motivo por el que el elemento de la solicitud es incorrecto.
reason

string

Es el motivo del error a nivel del campo. Este es un valor constante que identifica la causa próxima del error a nivel del campo. Debe identificar de forma única el tipo de FieldViolation dentro del alcance de google.rpc.ErrorInfo.domain. Debe tener un máximo de 63 caracteres y coincidir con una expresión regular de [A-Z][A-Z0-9_]+[A-Z0-9], que representa UPPER_SNAKE_CASE.
localized_message

LocalizedMessage

Proporciona un mensaje de error localizado para los errores a nivel del campo que se puede devolver de forma segura al consumidor de la API.

Código

Son los códigos de error canónicos para las APIs de gRPC.

A veces, es posible que se apliquen varios códigos de error. Los servicios deben devolver el código de error más específico que corresponda. Por ejemplo, se prefiere OUT_OF_RANGE por sobre FAILED_PRECONDITION, si se aplican ambos códigos. Del mismo modo, se prefiere NOT_FOUND o ALREADY_EXISTS por sobre FAILED_PRECONDITION.

Enums
OK

No es un error; se muestra si la operación tuvo éxito.

Asignación HTTP: 200 OK
CANCELLED

La operación se canceló (por lo general, la cancela el emisor).

Asignación HTTP: 499 Solicitud cerrada por el cliente
UNKNOWN

Error desconocido. Por ejemplo, este error puede mostrarse cuando un valor Status recibido de otro espacio de direcciones pertenece a un espacio de error desconocido en este espacio de direcciones. Además, los errores generados por API que no muestran suficiente información sobre el error pueden convertirse en este error.

Asignación HTTP: 500 Error interno del servidor
INVALID_ARGUMENT

El cliente especificó un argumento no válido. Ten en cuenta que esto difiere de FAILED_PRECONDITION. INVALID_ARGUMENT indica los argumentos que son problemáticos sin importar el estado del sistema (p. ej., un nombre de archivo con formato incorrecto).

Asignación HTTP: 400 Solicitud incorrecta
DEADLINE_EXCEEDED

El plazo venció antes de que la operación se pudiera completar. En el caso de las operaciones que cambian el estado del sistema, es probable que se muestre este error incluso si la operación se completó correctamente. Por ejemplo, una respuesta correcta desde un servidor podría haberse retrasado lo suficiente como para que el plazo venciera.

Asignación HTTP: 504 Tiempo de espera de la puerta de enlace
NOT_FOUND

No se encontró alguna entidad solicitada (p. ej., un archivo o un directorio).

Nota para los desarrolladores de servidores: Si se niega una solicitud a una clase completa de usuarios, como el lanzamiento gradual de funciones o una lista de entidades permitidas no documentada, se puede usar NOT_FOUND. Si se niega una solicitud a algunos usuarios de una clase, como el control de acceso basado en usuarios, se debe usar PERMISSION_DENIED.

Asignación HTTP: 404 No encontrado
ALREADY_EXISTS

La entidad que un cliente intentó crear (p. ej., un archivo o un directorio) ya existe.

Asignación HTTP: 409 Conflicto
PERMISSION_DENIED

El emisor de la llamada no tiene permiso para ejecutar la operación especificada. No se debe usar PERMISSION_DENIED para los rechazos causados por el agotamiento de algún recurso (en su lugar, usa RESOURCE_EXHAUSTED para esos errores). No se debe usar PERMISSION_DENIED si no se puede identificar al emisor (en su lugar, usa UNAUTHENTICATED para esos errores). Este código de error no sugiere que la solicitud sea válida o que la entidad solicitada exista o satisfaga otras condiciones previas.

Asignación HTTP: 403 Prohibido
UNAUTHENTICATED

La solicitud no tiene credenciales de autenticación válidas para la operación.

Asignación HTTP: 401 No autorizado
RESOURCE_EXHAUSTED

Algunos recursos se agotaron, tal vez una cuota por usuario, o tal vez se agotó el espacio de todo el sistema de archivos.

Asignación HTTP: 429 Demasiadas solicitudes
FAILED_PRECONDITION

La operación se rechazó debido a que el sistema no se encuentra en un estado necesario para la ejecución de la operación. Por ejemplo, el directorio que se borrará no está vacío, se aplicará una operación rmdir a un directorio que no sea de directorio, etcétera.

Los implementadores de servicios pueden usar los siguientes lineamientos para decidir entre FAILED_PRECONDITION, ABORTED y UNAVAILABLE: (a) Usa UNAVAILABLE si el cliente puede reintentar solo la llamada con errores. (b) Usa ABORTED si el cliente debe reintentar en un nivel superior. Por ejemplo, cuando falla una prueba y un conjunto especificados por el cliente, lo que indica que este deberá reiniciar una secuencia de lectura, modificación y escritura. (c) Usa FAILED_PRECONDITION si el cliente no debe volver a intentar hasta que el estado del sistema se haya corregido de forma explícita. Por ejemplo, si un “rmdir” falla porque el directorio no está vacío, se debe mostrar FAILED_PRECONDITION, ya que el cliente no debe reintentar, a menos que se borren los archivos del directorio.

Asignación HTTP: 400 Solicitud incorrecta
ABORTED

La operación se anuló, generalmente debido a un problema de simultaneidad, como una falla en la verificación del secuenciador o la anulación de la transacción.

Consulta los lineamientos anteriores para decidir entre FAILED_PRECONDITION, ABORTED y UNAVAILABLE.

Asignación HTTP: 409 Conflicto
OUT_OF_RANGE

La operación se intentó fuera del rango válido. P. ej., buscar o leer el final del archivo.

A diferencia de INVALID_ARGUMENT, este error indica un problema que se puede solucionar si cambia el estado del sistema. Por ejemplo, un sistema de archivos de 32 bits generará INVALID_ARGUMENT si se le pide que lea en un desplazamiento que no esté en el rango [0,2^32-1], pero generará OUT_OF_RANGE si se le solicita que lea desde un desplazamiento superior al tamaño del archivo actual.

Hay una leve superposición entre FAILED_PRECONDITION y OUT_OF_RANGE. Recomendamos usar OUT_OF_RANGE (el error más específico) cuando sea necesario, de modo que los emisores que iteran por medio de un espacio puedan buscar de forma sencilla un error OUT_OF_RANGE y, de esta manera, detectar cuando finalicen.

Asignación HTTP: 400 Solicitud incorrecta
UNIMPLEMENTED

La operación no se implementó, no se admite o no está habilitada en este servicio.

Asignación HTTP: 501 No implementado
INTERNAL

Errores internos. Esto significa que algunos invariantes que espera el sistema subyacente están rotos. Este código de error está reservado para errores graves.

Asignación HTTP: 500 Error interno del servidor
UNAVAILABLE

El servicio no está disponible actualmente. Lo más probable es que esta sea una condición transitoria y que se pueda corregir si vuelves a intentar una retirada. Ten en cuenta que no siempre es seguro reintentar operaciones no idempotentes.

Consulta los lineamientos anteriores para decidir entre FAILED_PRECONDITION, ABORTED y UNAVAILABLE.

Asignación HTTP: 503 Servicio no disponible
DATA_LOSS

Daño o pérdida de datos no recuperable.

Asignación HTTP: 500 Error interno del servidor

ErrorInfo

Describe la causa del error con detalles estructurados.

Ejemplo de un error cuando se contacta la API de "pubsub.googleapis.com" cuando no está habilitada:

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

Esta respuesta indica que la API de pubsub.googleapis.com no está habilitada.

Ejemplo de un error que se muestra cuando se intenta crear una instancia de Spanner en una región que está agotada:

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

string

El motivo del error. Este es un valor constante que identifica la causa próxima del error. Los motivos de error son únicos dentro de un dominio de errores en particular. Debe tener un máximo de 63 caracteres y coincidir con una expresión regular de [A-Z][A-Z0-9_]+[A-Z0-9], que representa UPPER_SNAKE_CASE.
domain

string

La agrupación lógica a la que pertenece el “motivo”. El dominio de error suele ser el nombre registrado del servicio de la herramienta o el producto que genera el error. Ejemplo: “pubsub.googleapis.com”. Si una infraestructura común genera el error, el dominio de error debe ser un valor único a nivel global que identifique la infraestructura. Para la infraestructura de la API de Google, el dominio de error es “googleapis.com”.
metadata

map<string, string>

Detalles estructurados adicionales sobre este error.

Las claves deben coincidir con una expresión regular de [a-z][a-zA-Z0-9-_]+, pero, idealmente, deberían ser lowerCamelCase. Además, deben tener un límite de 64 caracteres. Cuando se identifica el valor actual de un límite excedido, las unidades deben incluirse en la clave, no en el valor. Por ejemplo, en lugar de {"instanceLimit": "100/request"}, se debe mostrar como {"instanceLimitPerRequest": "100"} si el cliente supera la cantidad de instancias que se pueden crear en una sola solicitud (por lotes).

Ayuda

Proporciona vínculos a la documentación o para realizar una acción fuera de banda.

Por ejemplo, si una verificación de cuota falló con un error que indica que el proyecto que llama no habilitó el servicio al que se accedió, esto puede contener una URL que apunta directamente al lugar correcto en la consola para desarrolladores para cambiar el bit.

Campos

LocalizedMessage

Proporciona un mensaje de error localizado que se puede devolver al usuario de forma segura y que se puede adjuntar a un error de RPC.

Campos
locale

string

Es la configuración regional que se usa según la especificación definida en https://www.rfc-editor.org/rfc/bcp/bcp47.txt. Algunos ejemplos son "en-US", "fr-CH" y "es-MX".
message

string

Es el mensaje de error localizado en la configuración regional anterior.

PreconditionFailure

Describe qué condiciones previas no se cumplieron.

Por ejemplo, si una RPC falló porque requería que se reconocieran las Condiciones del Servicio, podría enumerar el incumplimiento de las Condiciones del Servicio en el mensaje de PreconditionFailure.

Campos
violations[]

Violation

Describe todos los incumplimientos de las condiciones previas.

Incumplimiento

Es un tipo de mensaje que se usa para describir una sola falla de condición previa.

Campos
type

string

Es el tipo de PreconditionFailure. Recomendamos usar un tipo de enumeración específico del servicio para definir los temas de incumplimiento de la condición previa admitidos. Por ejemplo, "TOS" para "incumplimiento de las Condiciones del Servicio".
subject

string

Es el asunto, en relación con el tipo, que falló. Por ejemplo, "google.com/cloud" en relación con el tipo "TOS" indicaría a qué condiciones del servicio se hace referencia.
description

string

Es una descripción de cómo falló la condición previa. Los desarrolladores pueden usar esta descripción para comprender cómo corregir la falla.

Por ejemplo, "No se aceptaron las Condiciones del Servicio".

QuotaFailure

Describe cómo falló una verificación de cuota.

Por ejemplo, si se excedió un límite diario para el proyecto que realiza la llamada, un servicio podría responder con un detalle de QuotaFailure que contenga el ID del proyecto y la descripción del límite de cuota que se excedió. Si el proyecto que realiza la llamada no habilitó el servicio en la consola para desarrolladores, un servicio podría responder con el ID del proyecto y establecer service_disabled como verdadero.

Consulta también los tipos RetryInfo y Help para obtener otros detalles sobre el manejo de una falla de cuota.

Campos
violations[]

Violation

Describe todos los incumplimientos de cuota.

Incumplimiento

Es un tipo de mensaje que se usa para describir un solo incumplimiento de la cuota. Por ejemplo, una cuota diaria o una cuota personalizada que se superó.

Campos
subject

string

Es el asunto sobre el que falló la verificación de la cuota. Por ejemplo, "clientip:" o "project:".
description

string

Es una descripción de cómo falló la verificación de cuota. Los clientes pueden usar esta descripción para obtener más información sobre la configuración de la cuota en la documentación pública del servicio o encontrar el límite de cuota pertinente para ajustarlo a través de la consola para desarrolladores.

Por ejemplo, "Servicio inhabilitado" o "Se excedió el límite diario para las operaciones de lectura".
api_service

string

Es el servicio de API desde el que se origina QuotaFailure.Violation. En algunos casos, los problemas de cuota se originan en un servicio de API diferente del que se llamó. En otras palabras, una dependencia del servicio de API llamado podría ser la causa del QuotaFailure, y este campo tendría el nombre del servicio de API de dependencia.

Por ejemplo, si la API llamada es la API de Kubernetes Engine (container.googleapis.com) y se produce un incumplimiento de la cuota en la propia API de Kubernetes Engine, este campo sería "container.googleapis.com". Por otro lado, si el incumplimiento de la cuota se produce cuando la API de Kubernetes Engine crea VMs en la API de Compute Engine (compute.googleapis.com), este campo sería "compute.googleapis.com".
quota_metric

string

Es la métrica de la cuota incumplida. Una métrica de cuota es un contador con nombre para medir el uso, como las solicitudes a la API o las CPU. Cuando se produce una actividad en un servicio, como la asignación de máquinas virtuales, se pueden ver afectadas una o más métricas de cuota.

Por ejemplo, "compute.googleapis.com/cpus_per_vm_family" o "storage.googleapis.com/internet_egress_bandwidth".
quota_id

string

Es el ID de la cuota incumplida. También conocido como "nombre del límite", es el identificador único de una cuota en el contexto de un servicio de API.

Por ejemplo, "CPUS-PER-VM-FAMILY-per-project-region".
quota_dimensions

map<string, string>

Son las dimensiones de la cuota incumplida. Cada cuota no global se aplica a un conjunto de dimensiones. Si bien la métrica de cuota define qué se debe contar, las dimensiones especifican para qué aspectos se debe aumentar el contador.

Por ejemplo, la cuota "CPUs per region per VM family" aplica un límite a la métrica "compute.googleapis.com/cpus_per_vm_family" en las dimensiones "region" y "vm_family". Si el incumplimiento se produjo en la región "us-central1" y para la familia de VMs "n1", quota_dimensions sería el siguiente:

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

Cuando se aplica una cuota de forma global, quota_dimensions siempre estaría vacío.
quota_value

int64

Es el valor de la cuota aplicada en el momento de la QuotaFailure.

Por ejemplo, si el valor de la cuota aplicada en el momento de QuotaFailure sobre la cantidad de CPU es "10", el valor de este campo reflejará esa cantidad.
future_quota_value

int64

Es el nuevo valor de la cuota que se implementó en el momento del incumplimiento. Cuando se complete el lanzamiento, este valor se aplicará en lugar de quota_value. Si no hay ningún lanzamiento en curso en el momento del incumplimiento, este campo no se establece.

Por ejemplo, si, en el momento del incumplimiento, se está realizando un lanzamiento que cambia la cuota de CPU de 10 a 20, 20 sería el valor de este campo.

RequestInfo

Contiene metadatos sobre la solicitud que los clientes pueden adjuntar cuando presentan un error o proporcionan otros tipos de comentarios.

Campos
request_id

string

Es una cadena opaca que solo debe interpretar el servicio que la genera. Por ejemplo, se puede usar para identificar solicitudes en los registros del servicio.
serving_data

string

Son los datos que se usaron para atender esta solicitud. Por ejemplo, un registro de seguimiento cifrado que se puede enviar al proveedor de servicios para la depuración.

ResourceInfo

Describe el recurso al que se accede.

Campos
resource_type

string

Un nombre para el tipo de recurso al que se accede, p. ej., "sql table", "bucket de Cloud Storage", "archivo" o "Calendario de Google"; o la URL del tipo del recurso: p. ej., "type.googleapis.com/google.pubsub.v1.Topic".
resource_name

string

El nombre del recurso al que se accede. Por ejemplo, un nombre de calendario compartido: “example.com_4fghdhgsrgh@group.calendar.google.com”, si el error actual es google.rpc.Code.PERMISSION_DENIED.
owner

string

El propietario del recurso (opcional). Por ejemplo, "usuario:" o "proyecto:".
description

string

Describe qué error se encuentra cuando se accede a este recurso. Por ejemplo, actualizar un proyecto de la nube puede requerir el permiso writer en el proyecto de la consola para desarrolladores.

RetryInfo

Describe cuándo los clientes pueden reintentar una solicitud fallida. Los clientes podrían ignorar la recomendación aquí o volver a intentarlo cuando falte esta información en las respuestas de error.

Siempre se recomienda que los clientes usen la retirada exponencial cuando reintenten.

Los clientes deben esperar hasta que transcurra la cantidad de tiempo retry_delay desde que recibieron la respuesta de error antes de reintentar la solicitud. Si los reintentos de solicitudes también fallan, los clientes deben usar un esquema de retirada exponencial para aumentar gradualmente la demora entre los reintentos según retry_delay, hasta que se alcance una cantidad máxima de reintentos o un límite máximo de demora de reintento.

Campos
retry_delay

Duration

Los clientes deben esperar al menos este tiempo antes de volver a intentar la misma solicitud.

Estado

El tipo de Status define un modelo de error lógico que es adecuado para entornos de programación diferentes, incluidas las API de REST y las API de RPC. Lo usa gRPC. Cada mensaje Status contiene tres datos: código de error, mensaje de error y detalles del error.

Puedes obtener más información sobre este modelo de error y cómo trabajar con él en la guía de diseño de API.

Campos
code

int32

El código de estado, que debe ser un valor enum de google.rpc.Code.
message

string

Un mensaje de error dirigido al desarrollador, que debe estar en inglés. Cualquier mensaje de error dirigido al usuario debe localizarse y enviarse al campo google.rpc.Status.details; o el cliente debe localizarlo.
details[]

Any

Una lista de mensajes que contienen los detalles del error. Hay un conjunto común de tipos de mensajes para que usen las API.