1// Copyright 2017 Google Inc.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15syntax = "proto3";
16
17package google.rpc;
18
19import "google/protobuf/duration.proto";
20
21option go_package = "google.golang.org/genproto/googleapis/rpc/errdetails;errdetails";
22option java_multiple_files = true;
23option java_outer_classname = "ErrorDetailsProto";
24option java_package = "com.google.rpc";
25option objc_class_prefix = "RPC";
26
27
28// Describes when the clients can retry a failed request. Clients could ignore
29// the recommendation here or retry when this information is missing from error
30// responses.
31//
32// It's always recommended that clients should use exponential backoff when
33// retrying.
34//
35// Clients should wait until `retry_delay` amount of time has passed since
36// receiving the error response before retrying. If retrying requests also
37// fail, clients should use an exponential backoff scheme to gradually increase
38// the delay between retries based on `retry_delay`, until either a maximum
39// number of retires have been reached or a maximum retry delay cap has been
40// reached.
41message RetryInfo {
42 // Clients should wait at least this long between retrying the same request.
43 google.protobuf.Duration retry_delay = 1;
44}
45
46// Describes additional debugging info.
47message DebugInfo {
48 // The stack trace entries indicating where the error occurred.
49 repeated string stack_entries = 1;
50
51 // Additional debugging information provided by the server.
52 string detail = 2;
53}
54
55// Describes how a quota check failed.
56//
57// For example if a daily limit was exceeded for the calling project,
58// a service could respond with a QuotaFailure detail containing the project
59// id and the description of the quota limit that was exceeded. If the
60// calling project hasn't enabled the service in the developer console, then
61// a service could respond with the project id and set `service_disabled`
62// to true.
63//
64// Also see RetryDetail and Help types for other details about handling a
65// quota failure.
66message QuotaFailure {
67 // A message type used to describe a single quota violation. For example, a
68 // daily quota or a custom quota that was exceeded.
69 message Violation {
70 // The subject on which the quota check failed.
71 // For example, "clientip:<ip address of client>" or "project:<Google
72 // developer project id>".
73 string subject = 1;
74
75 // A description of how the quota check failed. Clients can use this
76 // description to find more about the quota configuration in the service's
77 // public documentation, or find the relevant quota limit to adjust through
78 // developer console.
79 //
80 // For example: "Service disabled" or "Daily Limit for read operations
81 // exceeded".
82 string description = 2;
83 }
84
85 // Describes all quota violations.
86 repeated Violation violations = 1;
87}
88
89// Describes what preconditions have failed.
90//
91// For example, if an RPC failed because it required the Terms of Service to be
92// acknowledged, it could list the terms of service violation in the
93// PreconditionFailure message.
94message PreconditionFailure {
95 // A message type used to describe a single precondition failure.
96 message Violation {
97 // The type of PreconditionFailure. We recommend using a service-specific
98 // enum type to define the supported precondition violation types. For
99 // example, "TOS" for "Terms of Service violation".
100 string type = 1;
101
102 // The subject, relative to the type, that failed.
103 // For example, "google.com/cloud" relative to the "TOS" type would
104 // indicate which terms of service is being referenced.
105 string subject = 2;
106
107 // A description of how the precondition failed. Developers can use this
108 // description to understand how to fix the failure.
109 //
110 // For example: "Terms of service not accepted".
111 string description = 3;
112 }
113
114 // Describes all precondition violations.
115 repeated Violation violations = 1;
116}
117
118// Describes violations in a client request. This error type focuses on the
119// syntactic aspects of the request.
120message BadRequest {
121 // A message type used to describe a single bad request field.
122 message FieldViolation {
123 // A path leading to a field in the request body. The value will be a
124 // sequence of dot-separated identifiers that identify a protocol buffer
125 // field. E.g., "field_violations.field" would identify this field.
126 string field = 1;
127
128 // A description of why the request element is bad.
129 string description = 2;
130 }
131
132 // Describes all violations in a client request.
133 repeated FieldViolation field_violations = 1;
134}
135
136// Contains metadata about the request that clients can attach when filing a bug
137// or providing other forms of feedback.
138message RequestInfo {
139 // An opaque string that should only be interpreted by the service generating
140 // it. For example, it can be used to identify requests in the service's logs.
141 string request_id = 1;
142
143 // Any data that was used to serve this request. For example, an encrypted
144 // stack trace that can be sent back to the service provider for debugging.
145 string serving_data = 2;
146}
147
148// Describes the resource that is being accessed.
149message ResourceInfo {
150 // A name for the type of resource being accessed, e.g. "sql table",
151 // "cloud storage bucket", "file", "Google calendar"; or the type URL
152 // of the resource: e.g. "type.googleapis.com/google.pubsub.v1.Topic".
153 string resource_type = 1;
154
155 // The name of the resource being accessed. For example, a shared calendar
156 // name: "example.com_4fghdhgsrgh@group.calendar.google.com", if the current
157 // error is [google.rpc.Code.PERMISSION_DENIED][google.rpc.Code.PERMISSION_DENIED].
158 string resource_name = 2;
159
160 // The owner of the resource (optional).
161 // For example, "user:<owner email>" or "project:<Google developer project
162 // id>".
163 string owner = 3;
164
165 // Describes what error is encountered when accessing this resource.
166 // For example, updating a cloud project may require the `writer` permission
167 // on the developer console project.
168 string description = 4;
169}
170
171// Provides links to documentation or for performing an out of band action.
172//
173// For example, if a quota check failed with an error indicating the calling
174// project hasn't enabled the accessed service, this can contain a URL pointing
175// directly to the right place in the developer console to flip the bit.
176message Help {
177 // Describes a URL link.
178 message Link {
179 // Describes what the link offers.
180 string description = 1;
181
182 // The URL of the link.
183 string url = 2;
184 }
185
186 // URL(s) pointing to additional information on handling the current error.
187 repeated Link links = 1;
188}
189
190// Provides a localized error message that is safe to return to the user
191// which can be attached to an RPC error.
192message LocalizedMessage {
193 // The locale used following the specification defined at
194 // http://www.rfc-editor.org/rfc/bcp/bcp47.txt.
195 // Examples are: "en-US", "fr-CH", "es-MX"
196 string locale = 1;
197
198 // The localized error message in the above locale.
199 string message = 2;
200}
View as plain text