legacy-libs/dialogflow/src/v2/doc/google/rpc/doc_status.js

   1 // Copyright 2019 Google LLC
   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 //     https://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
  15 // Note: this file is purely for documentation. Any contents are not expected
  16 // to be loaded as the JS file.
  17
  18 /**
  19  * The `Status` type defines a logical error model that is suitable for
  20  * different programming environments, including REST APIs and RPC APIs. It is
  21  * used by [gRPC](https://github.com/grpc). The error model is designed to be:
  22  *
  23  * - Simple to use and understand for most users
  24  * - Flexible enough to meet unexpected needs
  25  *
  26  * # Overview
  27  *
  28  * The `Status` message contains three pieces of data: error code, error
  29  * message, and error details. The error code should be an enum value of
  30  * google.rpc.Code, but it may accept additional error codes
  31  * if needed.  The error message should be a developer-facing English message
  32  * that helps developers *understand* and *resolve* the error. If a localized
  33  * user-facing error message is needed, put the localized message in the error
  34  * details or localize it in the client. The optional error details may contain
  35  * arbitrary information about the error. There is a predefined set of error
  36  * detail types in the package `google.rpc` that can be used for common error
  37  * conditions.
  38  *
  39  * # Language mapping
  40  *
  41  * The `Status` message is the logical representation of the error model, but it
  42  * is not necessarily the actual wire format. When the `Status` message is
  43  * exposed in different client libraries and different wire protocols, it can be
  44  * mapped differently. For example, it will likely be mapped to some exceptions
  45  * in Java, but more likely mapped to some error codes in C.
  46  *
  47  * # Other uses
  48  *
  49  * The error model and the `Status` message can be used in a variety of
  50  * environments, either with or without APIs, to provide a
  51  * consistent developer experience across different environments.
  52  *
  53  * Example uses of this error model include:
  54  *
  55  * - Partial errors. If a service needs to return partial errors to the client,
  56  *     it may embed the `Status` in the normal response to indicate the partial
  57  *     errors.
  58  *
  59  * - Workflow errors. A typical workflow has multiple steps. Each step may
  60  *     have a `Status` message for error reporting.
  61  *
  62  * - Batch operations. If a client uses batch request and batch response, the
  63  *     `Status` message should be used directly inside batch response, one for
  64  *     each error sub-response.
  65  *
  66  * - Asynchronous operations. If an API call embeds asynchronous operation
  67  *     results in its response, the status of those operations should be
  68  *     represented directly using the `Status` message.
  69  *
  70  * - Logging. If some API errors are stored in logs, the message `Status` could
  71  *     be used directly after any stripping needed for security/privacy reasons.
  72  *
  73  * @property {number} code
  74  *   The status code, which should be an enum value of
  75  *   google.rpc.Code.
  76  *
  77  * @property {string} message
  78  *   A developer-facing error message, which should be in English. Any
  79  *   user-facing error message should be localized and sent in the
  80  *   google.rpc.Status.details field, or localized
  81  *   by the client.
  82  *
  83  * @property {Object[]} details
  84  *   A list of messages that carry the error details.  There is a common set of
  85  *   message types for APIs to use.
  86  *
  87  *   This object should have the same structure as [Any]{@link google.protobuf.Any}
  88  *
  89  * @typedef Status
  90  * @memberof google.rpc
  91  * @see [google.rpc.Status definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/rpc/status.proto}
  92  */
  93 const Status = {
  94   // This is for documentation. Actual contents will be loaded by gRPC.
  95 };