Rewrite ErrorInfo description

Note: this has removed the term "dynamic variables" in favor of only referring to it as "metadata". It's handy to have a single well-defined term, and given that the field name is `metatadata`, I've kept that.

Author: jskeet

aip/general/0193.md

@@ -51,12 +51,12 @@ developers to understand the problem and is more detailed than
 
 Messages **should** use simple descriptive language that is easy to understand
 (without technical jargon) to clearly state the problem that results in an
-error.
+error, and offer an actionable resolution to it.
 
-For pre-existing (brownfield) APIs which have returned errors without
-additional details in the past, the value of `message` must remain the same
-for any given error, as developers have previously had no option but to use
-this for error handling. For more information, see
+For pre-existing (brownfield) APIs which have previously returned errors
+without machine-readable identifiers, the value of `message` **must**
+remain the same for any given error, as developers have previously had no
+option but to use this for error handling. For more information, see
 [Changing Error Messages](#changing-error-messages).
 
 ### Status.code
@@ -96,121 +96,81 @@ The following sections describe the most common standard detail payloads.
 
 #### ErrorInfo
 
-The [`ErrorInfo`][ErrorInfo] message is the required way to send a
-machine-readable identifier. All error responses **must** include an
-`ErrorInfo` payload in `details`.  Variable information **should** be
+The [`ErrorInfo`][ErrorInfo] message is the primary way to send a
+machine-readable identifier. Contextual information **should** be
 included in `metadata` in `ErrorInfo` and **must** be included if it
 appears within an error message.
 
-When introducing an error that represents a failure scenario that did
-not previously occur for the service, the payload **must** include
-`ErrorInfo` and any variables found in dynamic segments of the error
-message **must** be present in `ErrorInfo.metadata` (See [Dynamic
-variables](#dynamic-variables).)
+The `reason` field is a short snake_case description of the cause of the
+error. Error reasons are unique within a particular domain of errors.
+The reason **must** be at most 63 characters and match a regular expression of
+`[A-Z][A-Z0-9_]+[A-Z0-9]`. (This is UPPER_SNAKE_CASE, without leading
+or trailing underscores, and without leading digits.)
 
-**Note:** `ErrorInfo` represents a special case. There **must** be
-exactly one `ErrorInfo`. It is required.
+The reason should be terse, but meaningful enough for a human reader to
+understand what the reason refers to.
 
-[ErrorInfo Payload][ErrorInfo]
+Good examples:
 
-Details of this object are summarized in the following fields, field
-descriptions, and examples:
+- `CPU_AVAILABILITY`
+- `NO_STOCK`
+- `CHECKED_OUT`
+- `AVAILABILITY_ERROR`
 
-- `reason string`
-  - A short snake_case description of why the error occurred. Error
-    reasons are unique within a particular domain of errors. The error
-    reason **must** do the following:
-  - Be at most 63 characters and match a regular expression of
-    `/[A-Z][A-Z0-9_]+[A-Z0-9]/`, which represents UPPER_SNAKE_CASE.
-  - 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`.
-
-- `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`
-
-- `metadata map`
-  - Additional structured details about this error, which **should**
-    provide important context for customers to identify resolution
-    steps.  Keys **should** match `/[a-z][a-zA-Z0-9-_]+/`, and be
-    limited to 64 characters in length. When identifying the current
-    value of an exceeded limit, the units **should** be contained in the
-    key, not the value.
-  - *Example*:
-    ```
-    "vmType": "e2-medium",
-    "attachment": "local-ssd=3,nvidia-t4=2",
-    "zone": "us-east1-a"
-    ```
-  - For guidance on using the metadata map, see [Dynamic
-    Variables](#dynamic-variables).
+Bad examples:
 
-##### Dynamic variables
+- `THE_BOOK_YOU_WANT_IS_NOT_AVAILABLE` (overly verbose)
+- `ERROR` (too general)
 
-The best, actionable error messages include dynamic segments. These
-variable parts of the message are specific to a particular request.
-Without such context, it is unlikely that the message will be fully
-actionable by the user.
+The `domain` field is the logical grouping to which the `reason` belongs.
+The domain **must** be a globally unique value, and is typically the name of the service
+that generated the error, e.g. `pubsub.googleapis.com`.
 
-This practice is critical so that machine actors do not need to rely on
-`LocalizedMessage.message`, which is subject to change and is not part
-of the API contract.
+The (reason, domain) pair form a machine-readable way of identifying a particular error.
+Services **must** use the same (reason, domain) pair for the same error, and
+**must not** use the same (reason, domain) pair for logically different errors.
+The decision about whether two errors are "the same" or not is not always clear, but
+**should** generally be considered in terms of the expected action a client might take
+to resolve them.
 
-Consider the following example:
+The `metadata` field is a map of key/value pairs providing additional
+dynamic information as context. Each key within `metadata` **must** be at most
+64 characters long, and conform to the regular expression `[a-z][a-zA-Z0-9-_]+`.
 
-> The Book, "The Great Gatsby", is unavailable at the Library, "Garfield
-> East".  It is expected to be available again on 2199-05-13.
+Any request-specific information which contributes to the `Status.message` or
+`LocalizedMessage.message` messages **must** be represented within `metadata`.
+This practice is critical so that machine actors do not need to parse error
+messages to extract information.
 
-The preceding error message is made actionable by the context, both
-originating from the request, the title of the Book, the name of the
-Library, and by the information that is known only by the service, that
-is, the expected return date of the Book.
+For example consider the following message:
 
-All dynamic variables found in error messages **must** also be present
-in the `map<string, string>`, `ErrorInfo.metadata` (found on the
-*required* `ErrorInfo`). For example, the `metadata` map for the sample
-error message above will include *at least* the following key/value
-pairs:
+> An &lt;e2-medium&gt; VM instance with &lt;local-ssd=3,nvidia-t4=2&gt; is currently unavailable
+> in the &lt;us-east1-a&gt; zone. Consider trying your request in the &lt;us-central1-f,us-central1-c&gt;
+> zone(s), which currently has/have capacity to accommodate your request. Alternatively,
+> you can try your request again with a different VM hardware configuration
+> or at a later time. For more information, see the troubleshooting documentation.
 
-```
-bookTitle: "The Great Gatsby"
-library: "Garfield East"
-expectedReturnDate: "2199-05-13"
-```
+The `ErrorInfo.metadata` map for the same error could be:
 
-The following example shows an additional example of a metadata map for
-information about virtual machines:
+- `"zone": "us-east1-a"`
+- `"vmType": "e2-medium"`
+- `"attachment": "local-ssd=3,nvidia-t4=2"`
+- `"zonesWithCapacity": "us-central1-f,us-central1-c"`
 
-```
-vmType: "<VM-TYPE>",
-attachment: "<ATTACHMENT>"
-zone: "<ZONE>"
-```
+Additional contextual information that does not appear in an error message
+**may** also be included in `metadata` to allow programmatic use by the client.
+
+The metadata included for any given (reason,domain) pair can evolve over time:
+
+- New keys **may** be included
+- All keys that have been included **must** continue to be included (but may have empty values)
 
-Dynamic variables that do not appear in an error message **may** also be
-included in `metadata` to provide additional information to the client
-to be used programmatically.
+In other words, once a user has observed a given key for a (reason, domain) pair, the
+service **must** allow them to rely on it continuing to be present in the future.
 
-Once present in `metadata`, keys **must** continue to be included in the
-map for the error payload to be backwards compatible, even if the value
-for a particular key is empty. Keys **must** be expressed as lower
-camel-case.
+The set of keys provided in each (reason, domain) pair is independent from other pairs,
+but services **should** aim for consistent key naming. For example, two error reasons
+within the same domain should not use metadata keys of `vmType` and `virtualMachineType`.
 
 #### Localization