Updated AIP 193 (Errors) to include ErrorInfo retirement

aip/general/0193.md

@@ -12,46 +12,95 @@ placement:
 Effective error communication is an important part of designing simple and
 intuitive APIs. Services returning standardized error responses enable API
 clients to construct centralized common error handling logic. This common logic
-simplifies API client appications and eliminates the need for cumbersome
+simplifies API client applications and eliminates the need for cumbersome
 custom error handling code.
 
 ## Guidance
 
-Services **must** return a [`google.rpc.Status`][Status] message when an API
-error occurs, and **must** use the canonical error codes defined in
-[`google.rpc.Code`][Code]. More information about the particular codes is
-available in the [gRPC status code documentation][].
+Services that encounter an error **must** return a
+[`google.rpc.Status`][Status] message.
 
-Error messages **should** help a reasonably technical user _understand_ and
-_resolve_ the issue, and **should not** assume that the user is an expert in
-your particular API. Additionally, error messages **must not** assume that the
-user will know anything about its underlying implementation.
+### Example Response
 
-Error messages **should** be brief but actionable. Any extra 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.
+```proto
+code: 429
+message: "The zone 'projects/<project-id>/zones/us-west1-b'..."
+details: [
+  [google.rpc.ErrorInfo]: {
+    reason: "STOCKOUT",
+    domain: "compute.googleapis.com",
+    metadata: {
+      maxInstances: 200
+      usedInstances: 190
+      requestedInstances: 30
+    }
+  },
+  [google.rpc.LocalizedMessage]: {
+    locale: "en-US",
+    message: "The zone 'projects/<project-id>/zones/us-west1-b'..."
+  }
+]
+```
 
-### Details
+### Fields
 
-Google defines a set of [standard detail payloads][details] for error details,
-which cover most common needs for API errors. Services **should** use these
-standard details payloads when feasible.
+#### `code`
 
-Structured details with machine-readable identifiers **must** be used if users
-will need to write code against a specific aspect of the error. Error message
-strings **may** change over time; however, if an error message does not have a
-machine-readable identifier _in addition to_ the `code` field, changing the
-error message **must** be considered a backwards-incompatible change.
+The `code` field in the error response message **must** use the
+canonical error codes defined in [`google.rpc.Code`][Code].
+[gRPC status code documentation][] provides details about the types and
+usage of the canonical error codes.
 
-**Note:** The [`ErrorInfo`][ErrorInfo] message is the recommended way to send a
-machine-readable identifier.
+#### `message`
 
-### Localization
+The `google.rpc.Status` response **must** include the `message` field.
+The `message` field's text:
 
-Error messages **must** be in English. If a localized error message is also
-required, the service **should** use [`google.rpc.LocalizedMessage`][details]
-as the `details` field.
+* **should** help a reasonably technical user _understand_ and _resolve_
+the underlying issue.
+* **must not** assume that the user will know anything about the erroring
+system's underlying implementation.
+* **should not** assume that the user is an expert in your particular API.
+* **should** be brief and actionable.
+
+In an event where returned error would require an extensive explanation or
+technical support help, the error message **should** provide a links to such
+resources.
+
+#### `details`
+
+The repeated `details` field
+
+* **must** include a single `ErrorInfo` message
+* **should** include a `LocalizedMessage` message
+* **may** include other messages defined in [standard payloads][details].
+
+### Extensions
+
+#### `ErrorInfo`
+
+API clients often write automation code that interpret services' AIP responses.
+When machine readable information is unavailable, clients parse and interpret
+response string included in the `message` field. Updates to a client parsed
+`message` field **must** be considered a backwards-incompatible change.
+
+To discourage clients' string parsing practice services **must** include
+the `ErrorInfo` extension in the returned `Status` message.
+
+Changes to the structure of the `ErrorInfo` field **must** be considered
+backwards-incompatible.
+
+#### `LocalizedMessage`
+
+Error messages **must** be in English. If a service provides localizations
+the service **should** use [`google.rpc.LocalizedMessage`][details] extension
+and include it in the `details` field.
+
+##### Legacy system usage
+For legacy systems where the top level `message` field in the `Status` message
+has been parsed by clients the `LocalizatizedMessage` extension **should** be
+included in the error response. The inclusion of `LocalizatizedMessage` extension
+**must** be accompanied by inclusion of the `ErrorInfo` extension.
 
 ### Partial errors
 
@@ -76,6 +125,7 @@ message. The errors themselves **must** still be represented with a
 
 ## Changelog
 
+- **2022-08-23**: Added ErrorInfo requirement and guidance for LocalizedMessage.
 - **2022-08-12**: Reworded/Simplified intro to add clarity to the intent.
 - **2020-01-22**: Added a reference to the [`ErrorInfo`][ErrorInfo] message.
 - **2019-10-14**: Added guidance restricting error message mutability to if