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.