Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Clean up and promote AIP-193 to published #1336

Closed
wants to merge 1 commit into from
Closed

Clean up and promote AIP-193 to published #1336

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
54 changes: 18 additions & 36 deletions aip/general/0193.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
---
id: 193
state: draft
state: published
created: 2019-07-26
updated: 2024-04-02
placement:
category: polish
order: 30
Expand Down Expand Up @@ -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.
Expand All @@ -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": {
Expand Down Expand Up @@ -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]
Expand Down Expand Up @@ -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<br>
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*:<br>`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
Expand Down Expand Up @@ -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

Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand Down