yandex_cloud/google.rpc.rs
1/// The `Status` type defines a logical error model that is suitable for different
2/// programming environments, including REST APIs and RPC APIs. It is used by
3/// \[gRPC\](<https://github.com/grpc>). The error model is designed to be:
4///
5/// - Simple to use and understand for most users
6/// - Flexible enough to meet unexpected needs
7///
8/// # Overview
9///
10/// The `Status` message contains three pieces of data: error code, error message,
11/// and error details. The error code should be an enum value of
12/// \[google.rpc.Code][google.rpc.Code\], but it may accept additional error codes if needed. The
13/// error message should be a developer-facing English message that helps
14/// developers *understand* and *resolve* the error. If a localized user-facing
15/// error message is needed, put the localized message in the error details or
16/// localize it in the client. The optional error details may contain arbitrary
17/// information about the error. There is a predefined set of error detail types
18/// in the package `google.rpc` that can be used for common error conditions.
19///
20/// # Language mapping
21///
22/// The `Status` message is the logical representation of the error model, but it
23/// is not necessarily the actual wire format. When the `Status` message is
24/// exposed in different client libraries and different wire protocols, it can be
25/// mapped differently. For example, it will likely be mapped to some exceptions
26/// in Java, but more likely mapped to some error codes in C.
27///
28/// # Other uses
29///
30/// The error model and the `Status` message can be used in a variety of
31/// environments, either with or without APIs, to provide a
32/// consistent developer experience across different environments.
33///
34/// Example uses of this error model include:
35///
36/// - Partial errors. If a service needs to return partial errors to the client,
37/// it may embed the `Status` in the normal response to indicate the partial
38/// errors.
39///
40/// - Workflow errors. A typical workflow has multiple steps. Each step may
41/// have a `Status` message for error reporting.
42///
43/// - Batch operations. If a client uses batch request and batch response, the
44/// `Status` message should be used directly inside batch response, one for
45/// each error sub-response.
46///
47/// - Asynchronous operations. If an API call embeds asynchronous operation
48/// results in its response, the status of those operations should be
49/// represented directly using the `Status` message.
50///
51/// - Logging. If some API errors are stored in logs, the message `Status` could
52/// be used directly after any stripping needed for security/privacy reasons.
53#[allow(clippy::derive_partial_eq_without_eq)]
54#[derive(Clone, PartialEq, ::prost::Message)]
55pub struct Status {
56 /// The status code, which should be an enum value of \[google.rpc.Code][google.rpc.Code\].
57 #[prost(int32, tag = "1")]
58 pub code: i32,
59 /// A developer-facing error message, which should be in English. Any
60 /// user-facing error message should be localized and sent in the
61 /// \[google.rpc.Status.details][google.rpc.Status.details\] field, or localized by the client.
62 #[prost(string, tag = "2")]
63 pub message: ::prost::alloc::string::String,
64 /// A list of messages that carry the error details. There is a common set of
65 /// message types for APIs to use.
66 #[prost(message, repeated, tag = "3")]
67 pub details: ::prost::alloc::vec::Vec<::prost_types::Any>,
68}
69/// The canonical error codes for Google APIs.
70///
71///
72/// Sometimes multiple error codes may apply. Services should return
73/// the most specific error code that applies. For example, prefer
74/// `OUT_OF_RANGE` over `FAILED_PRECONDITION` if both codes apply.
75/// Similarly prefer `NOT_FOUND` or `ALREADY_EXISTS` over `FAILED_PRECONDITION`.
76#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, ::prost::Enumeration)]
77#[repr(i32)]
78pub enum Code {
79 /// Not an error; returned on success
80 ///
81 /// HTTP Mapping: 200 OK
82 Ok = 0,
83 /// The operation was cancelled, typically by the caller.
84 ///
85 /// HTTP Mapping: 499 Client Closed Request
86 Cancelled = 1,
87 /// Unknown error. For example, this error may be returned when
88 /// a `Status` value received from another address space belongs to
89 /// an error space that is not known in this address space. Also
90 /// errors raised by APIs that do not return enough error information
91 /// may be converted to this error.
92 ///
93 /// HTTP Mapping: 500 Internal Server Error
94 Unknown = 2,
95 /// The client specified an invalid argument. Note that this differs
96 /// from `FAILED_PRECONDITION`. `INVALID_ARGUMENT` indicates arguments
97 /// that are problematic regardless of the state of the system
98 /// (e.g., a malformed file name).
99 ///
100 /// HTTP Mapping: 400 Bad Request
101 InvalidArgument = 3,
102 /// The deadline expired before the operation could complete. For operations
103 /// that change the state of the system, this error may be returned
104 /// even if the operation has completed successfully. For example, a
105 /// successful response from a server could have been delayed long
106 /// enough for the deadline to expire.
107 ///
108 /// HTTP Mapping: 504 Gateway Timeout
109 DeadlineExceeded = 4,
110 /// Some requested entity (e.g., file or directory) was not found.
111 ///
112 /// Note to server developers: if a request is denied for an entire class
113 /// of users, such as gradual feature rollout or undocumented whitelist,
114 /// `NOT_FOUND` may be used. If a request is denied for some users within
115 /// a class of users, such as user-based access control, `PERMISSION_DENIED`
116 /// must be used.
117 ///
118 /// HTTP Mapping: 404 Not Found
119 NotFound = 5,
120 /// The entity that a client attempted to create (e.g., file or directory)
121 /// already exists.
122 ///
123 /// HTTP Mapping: 409 Conflict
124 AlreadyExists = 6,
125 /// The caller does not have permission to execute the specified
126 /// operation. `PERMISSION_DENIED` must not be used for rejections
127 /// caused by exhausting some resource (use `RESOURCE_EXHAUSTED`
128 /// instead for those errors). `PERMISSION_DENIED` must not be
129 /// used if the caller can not be identified (use `UNAUTHENTICATED`
130 /// instead for those errors). This error code does not imply the
131 /// request is valid or the requested entity exists or satisfies
132 /// other pre-conditions.
133 ///
134 /// HTTP Mapping: 403 Forbidden
135 PermissionDenied = 7,
136 /// The request does not have valid authentication credentials for the
137 /// operation.
138 ///
139 /// HTTP Mapping: 401 Unauthorized
140 Unauthenticated = 16,
141 /// Some resource has been exhausted, perhaps a per-user quota, or
142 /// perhaps the entire file system is out of space.
143 ///
144 /// HTTP Mapping: 429 Too Many Requests
145 ResourceExhausted = 8,
146 /// The operation was rejected because the system is not in a state
147 /// required for the operation's execution. For example, the directory
148 /// to be deleted is non-empty, an rmdir operation is applied to
149 /// a non-directory, etc.
150 ///
151 /// Service implementors can use the following guidelines to decide
152 /// between `FAILED_PRECONDITION`, `ABORTED`, and `UNAVAILABLE`:
153 /// (a) Use `UNAVAILABLE` if the client can retry just the failing call.
154 /// (b) Use `ABORTED` if the client should retry at a higher level
155 /// (e.g., when a client-specified test-and-set fails, indicating the
156 /// client should restart a read-modify-write sequence).
157 /// (c) Use `FAILED_PRECONDITION` if the client should not retry until
158 /// the system state has been explicitly fixed. E.g., if an "rmdir"
159 /// fails because the directory is non-empty, `FAILED_PRECONDITION`
160 /// should be returned since the client should not retry unless
161 /// the files are deleted from the directory.
162 ///
163 /// HTTP Mapping: 400 Bad Request
164 FailedPrecondition = 9,
165 /// The operation was aborted, typically due to a concurrency issue such as
166 /// a sequencer check failure or transaction abort.
167 ///
168 /// See the guidelines above for deciding between `FAILED_PRECONDITION`,
169 /// `ABORTED`, and `UNAVAILABLE`.
170 ///
171 /// HTTP Mapping: 409 Conflict
172 Aborted = 10,
173 /// The operation was attempted past the valid range. E.g., seeking or
174 /// reading past end-of-file.
175 ///
176 /// Unlike `INVALID_ARGUMENT`, this error indicates a problem that may
177 /// be fixed if the system state changes. For example, a 32-bit file
178 /// system will generate `INVALID_ARGUMENT` if asked to read at an
179 /// offset that is not in the range \[0,2^32-1\], but it will generate
180 /// `OUT_OF_RANGE` if asked to read from an offset past the current
181 /// file size.
182 ///
183 /// There is a fair bit of overlap between `FAILED_PRECONDITION` and
184 /// `OUT_OF_RANGE`. We recommend using `OUT_OF_RANGE` (the more specific
185 /// error) when it applies so that callers who are iterating through
186 /// a space can easily look for an `OUT_OF_RANGE` error to detect when
187 /// they are done.
188 ///
189 /// HTTP Mapping: 400 Bad Request
190 OutOfRange = 11,
191 /// The operation is not implemented or is not supported/enabled in this
192 /// service.
193 ///
194 /// HTTP Mapping: 501 Not Implemented
195 Unimplemented = 12,
196 /// Internal errors. This means that some invariants expected by the
197 /// underlying system have been broken. This error code is reserved
198 /// for serious errors.
199 ///
200 /// HTTP Mapping: 500 Internal Server Error
201 Internal = 13,
202 /// The service is currently unavailable. This is most likely a
203 /// transient condition, which can be corrected by retrying with
204 /// a backoff.
205 ///
206 /// See the guidelines above for deciding between `FAILED_PRECONDITION`,
207 /// `ABORTED`, and `UNAVAILABLE`.
208 ///
209 /// HTTP Mapping: 503 Service Unavailable
210 Unavailable = 14,
211 /// Unrecoverable data loss or corruption.
212 ///
213 /// HTTP Mapping: 500 Internal Server Error
214 DataLoss = 15,
215}
216impl Code {
217 /// String value of the enum field names used in the ProtoBuf definition.
218 ///
219 /// The values are not transformed in any way and thus are considered stable
220 /// (if the ProtoBuf definition does not change) and safe for programmatic use.
221 pub fn as_str_name(&self) -> &'static str {
222 match self {
223 Code::Ok => "OK",
224 Code::Cancelled => "CANCELLED",
225 Code::Unknown => "UNKNOWN",
226 Code::InvalidArgument => "INVALID_ARGUMENT",
227 Code::DeadlineExceeded => "DEADLINE_EXCEEDED",
228 Code::NotFound => "NOT_FOUND",
229 Code::AlreadyExists => "ALREADY_EXISTS",
230 Code::PermissionDenied => "PERMISSION_DENIED",
231 Code::Unauthenticated => "UNAUTHENTICATED",
232 Code::ResourceExhausted => "RESOURCE_EXHAUSTED",
233 Code::FailedPrecondition => "FAILED_PRECONDITION",
234 Code::Aborted => "ABORTED",
235 Code::OutOfRange => "OUT_OF_RANGE",
236 Code::Unimplemented => "UNIMPLEMENTED",
237 Code::Internal => "INTERNAL",
238 Code::Unavailable => "UNAVAILABLE",
239 Code::DataLoss => "DATA_LOSS",
240 }
241 }
242 /// Creates an enum from field names used in the ProtoBuf definition.
243 pub fn from_str_name(value: &str) -> ::core::option::Option<Self> {
244 match value {
245 "OK" => Some(Self::Ok),
246 "CANCELLED" => Some(Self::Cancelled),
247 "UNKNOWN" => Some(Self::Unknown),
248 "INVALID_ARGUMENT" => Some(Self::InvalidArgument),
249 "DEADLINE_EXCEEDED" => Some(Self::DeadlineExceeded),
250 "NOT_FOUND" => Some(Self::NotFound),
251 "ALREADY_EXISTS" => Some(Self::AlreadyExists),
252 "PERMISSION_DENIED" => Some(Self::PermissionDenied),
253 "UNAUTHENTICATED" => Some(Self::Unauthenticated),
254 "RESOURCE_EXHAUSTED" => Some(Self::ResourceExhausted),
255 "FAILED_PRECONDITION" => Some(Self::FailedPrecondition),
256 "ABORTED" => Some(Self::Aborted),
257 "OUT_OF_RANGE" => Some(Self::OutOfRange),
258 "UNIMPLEMENTED" => Some(Self::Unimplemented),
259 "INTERNAL" => Some(Self::Internal),
260 "UNAVAILABLE" => Some(Self::Unavailable),
261 "DATA_LOSS" => Some(Self::DataLoss),
262 _ => None,
263 }
264 }
265}