From 612bd77cb9396ecb7e998c65d4c30b33a1072979 Mon Sep 17 00:00:00 2001 From: Andrei Scripniciuc <46186670+andrei-scripniciuc@users.noreply.github.com> Date: Tue, 2 Apr 2024 11:48:28 -0700 Subject: [PATCH] Clean up and promote AIP-193 to published --- aip/general/0193.md | 54 +++++++++++++++------------------------------ 1 file changed, 18 insertions(+), 36 deletions(-) diff --git a/aip/general/0193.md b/aip/general/0193.md index a9663e42b..6dcac5e4a 100644 --- a/aip/general/0193.md +++ b/aip/general/0193.md @@ -1,7 +1,8 @@ --- id: 193 -state: draft +state: published created: 2019-07-26 +updated: 2024-04-02 placement: category: polish order: 30 @@ -29,7 +30,7 @@ assume that the user will know anything about its underlying implementation. Error messages **should** be brief but actionable. Any extra information -**should** be provided in the `details`field. If even more information +**should** be provided in the `details` field. If even more information is necessary, you **should** provide a link where a reader can get more information or ask questions to help resolve the issue. It is also important to [set the right tone][writing-tone] when writing messages. @@ -41,12 +42,6 @@ important to [set the right tone][writing-tone] when writing messages. A JSON representation of an error response might look like the following example. -For the purposes of following best practices, it’s helpful to break the -error response into sections. Note that the order in which you write the -error message is often different from how the error is presented to -users. - - ```json { "error": { @@ -130,12 +125,12 @@ descriptions, and examples: + A developer-facing error message, which **should** be in English. Any user-facing error message **should** be located in the LocalizedMessage payload. - + *Example message*: \"The zone \'us-east1-a\' does not have enough + + *Example message*: `"The zone 'us-east1-a' does not have enough resources available to fulfill the request. Try a different zone, or - try again later.\" -+ `details Object (repeated)` + try again later."` ++ `repeated google.protobuf.Any details` + Additional text details about the error, which includes - `ErrorInfo`,`LocalizedMessage`, and so on. + `ErrorInfo`, `LocalizedMessage`, and so on. + *Example*: Described in the [ErrorDetails](#error-details) section. #### [ErrorDetails][details] @@ -192,24 +187,12 @@ descriptions, and examples: + Be meaningful enough for a human reader to understand what the reason refers to. + Be unique and consumable by machine actors for automation. - + *Example*: CPU_AVAILABILITY
- Distill your error message into its simplest form. For example, the - `reason string` could be one of the following text examples in - UPPER_SNAKE_CASE: `UNAVAILABLE`, `NO_STOCK`, `CHECKED_OUT`, - `AVAILABILITY_ERROR`, if your error message is, - - > The Book, "The Great Gatsby", is unavailable at the Library, - > "Garfield East". It is expected to be available again on 2199-05-13. - - + In contrast, using either of the following reasons is not - recommended: `THE_BOOK_YOU_WANT_IS_NOT_AVAILABLE`, `ERROR`. And, - using either of the following reasons breaches the required - formatting and is not allowed: `librariesAreGreat`, `noBooks`. + + *Example*: `CPU_AVAILABILITY` + `domain string` + The logical grouping to which the `reason` belongs. The error domain is typically the registered service name of the tool or product that generated the error. The domain must be a globally unique value. - + *Example*:
`pubsub.googleapis.com` + + *Example*: `pubsub.googleapis.com` + `metadata map` + Additional structured details about this error, which **should** provide important context for customers to identify resolution @@ -348,12 +331,12 @@ descriptions, and examples: - `description string` - Describes what the link offers. - - *Example*: "Troubleshooting documentation for STOCKOUT errors" + - *Example*: `"Troubleshooting documentation for STOCKOUT errors"` - `url string` - The URL of the link. For error documentation this must follow the standardized format listed in the following example. - *Example*: - https://cloud.google.com/PRODUCT/docs/ERROR-REASON + `"https://cloud.google.com/PRODUCT/docs/ERROR-REASON"` ### Error messages @@ -370,17 +353,16 @@ payload is present in the message. If the error message contains ErrorInfo payload (a machine-readable identifier): -+ `Status.message` *string* and `LocalizedMessage.message` *string* can - change -+ New metadata fields can be added ++ `Status.message` and `LocalizedMessage.message` **may** change ++ New metadata fields **may** be added + However, existing metadata fields **must not** be removed and existing - metadata field keys cannot be modified. + metadata field keys **must not** be modified. -If the error message does *not* contain ErrorInfo payload (usually for +If the error message does not contain ErrorInfo payload (usually for pre-existing APIs): -+ The `LocalizedMessage.message` *string* can change -+ However, the `Status.message` *string* **must** not be changed, as ++ The `LocalizedMessage.message` string **may** change ++ However, the `Status.message` *string* **must not** be changed, as this change is backward-incompatible. ##### Message alignment @@ -502,7 +484,7 @@ data instead. ## Changelog -+ **2024-01-10**: Incorporate guidance for writing effective messages. ++ **2024-04-02**: Incorporate guidance for writing effective messages. + **2023-05-17**: Change the recommended language for `Status.message` to be the service's native language rather than English. + **2023-05-17**: Specify requirements for changing error messages.