AIP-193: First part of restructuring the description of Status fields

(This doesn't include anything about the details "payloads" yet.)

Author: jskeet

aip/general/0193.md

@@ -34,98 +34,67 @@ 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.
 
-### Error Response
-
-#### google.rpc.Status
-
-Services must return a [`google.rpc.Status`][Status] message when an API
-error occurs. For each error the service **must** populate the `message`
-string in [`google.rpc.Status`][Status] as follows:
-
-- Present a developer-facing, human-readable "debug message"
-- Present the message in the service's native language to explain both
-  the error and offer an actionable resolution to it ([citation][Error
-  model])
-
-**Note:** Sometimes a service will elect to always present
-`Status.message` in English rather than the application's native
-language so that messages are easily searchable in common knowledge
-bases, such as StackOverflow™.
-
-Important points:
-
-- This `message` string is considered a problem description. It is
-  intended for developers to understand the problem and is more
-  detailed than [`ErrorInfo.reason`][ErrorInfo-reason], discussed in the
-  next section.
-- Use simple descriptive language that is easy to understand (without
-  technical jargon) to clearly state the problem that results in an
-  error.
-- For pre-existing (brownfield) APIs, the information in
-  `google.rpc.Status` already exists and can’t be changed. In this
-  case, do not edit anything in this `google.rpc.Status`, because some
-  users might have automation running against the pre-existing content.
-  For example, any changes in text for the `message` string could cause
-  breakages. For more information, see [Changing Error
-  Messages](#changing-error-messages).
-
-##### [google.rpc.Status payload][Status]
+The following sections describe the fields of `google.rpc.Status`.
 
-Details of this object are summarized in the following fields, field
-descriptions, and examples:
+### Status.message
 
-- `code int32`
-  - The status code, which **must** be an enum value of
-    [`google.rpc.Code`][Code].
-  - *Example*: 8
-- `message string`
-  - 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
-    resources available to fulfill the request. Try a different zone, or
-    try again later.\"
-- `details Object (repeated)`
-  - Additional text details about the error, which includes
-    `ErrorInfo`,`LocalizedMessage`, and so on.
-  - *Example*: Described in the [ErrorDetails](#error-details) section.
-
-
-**Important:** In the context of the `google.rpc.Status` protobuf
-message, the value of the field `code` is the numeric equivalent to the
-enum value chosen from [`google.rpc.Code`][Code]. For example, if
-[`INVALID_ARGUMENT`][InvalidArgument] is chosen, the value of `code`
-will be `3` (in the context of the Protobuf message,
-`google.rpc.Status`). However, when the error is expressed as JSON, as
-in the [sample above](#json-representation), the value of the field by
-the same name, `"code"`, is the HTTP status code equivalent of the
-selected `google.rpc.Code`. For example, the value of the field `"code"`
-in the JSON reply would be `400`.
-
-#### [ErrorDetails][details]
+The `message` field is a developer-facing, human-readable "debug message"
+which **should** be in English. (Localized messages are expressed using
+a `LocalizedMessage` within the `details` field. See
+[`LocalizedMessage`](#localizedmessage) for more details.) Any dynamic aspects of
+the message **must** be included as metadata within the `ErrorInfo` that appears
+in [`details`](#status-details).
 
-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 detail payloads when feasible.
+The message is considered a problem description. It is intended for
+developers to understand the problem and is more detailed than
+[`ErrorInfo.reason`][ErrorInfo-reason], discussed [later](#errorinfo).
 
-Structured details with machine-readable identifiers **must** be used so
-that users can write code against specific aspects 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`
-string, changing the error message **must** be considered a
-backwards-incompatible change.
+Messages **should** use simple descriptive language that is easy to understand
+(without technical jargon) to clearly state the problem that results in an
+error.
+
+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
+[Changing Error Messages](#changing-error-messages).
+
+### Status.code
+
+The `code` field is the status code, which **must** be the numeric value of
+one of the elements of the [`google.rpc.Code`][Code] enum.
 
-The following section describes `ErrorInfo`, `LocalizedMessage`, and
-`Help` in more detail.
+For example, the value `5` is the numeric value of the `NOT_FOUND`
+enum element.
 
-##### Uniqueness
+### Status.details
+
+The `details` field allows messages with additional error information to
+be included in the error response, each packed in a `google.protobuf.Any`
+message.
+
+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 detail payloads when feasible.
 
 Each type of detail payload **must** be included at most once. For
 example, there **must not** be more than one [`BadRequest`][BadRequest]
 message in the `details`, but there **may** be a `BadRequest` and a
 [`PreconditionFailure`][PreconditionFailure].
 
-##### ErrorInfo payload
+Structured details with machine-readable identifiers **must** be used so
+that users can write code against specific aspects 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 message,
+changing the error message **must** be considered a backwards-incompatible
+change. For more information, see
+[Changing Error Messages](#changing-error-messages).
+
+All error responses **must** include an `ErrorInfo` message within `details`.
+
+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
@@ -243,15 +212,15 @@ 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.
 
-##### Localization
+#### Localization
 
 If a localized error message is required, the service **must** include
 [`google.rpc.LocalizedMessage`][LocalizedMessage] in `Status.details`.
 The value of the `Status.message` string **should** be presented in the
 service's native language in the `LocalizedMessage.message` string,
 while also ensuring that the `locale` string shows the correct language.
 
-##### LocalizedMessage payload
+#### LocalizedMessage payload
 
 The LocalizedMessage payload **should** contain the complete resolution
 to the error. If more information is needed than can fit in this
@@ -293,7 +262,7 @@ descriptions, and examples:
     common resolution in the message and use the `Help` payload to
     link to relevant documentation.
 
-##### Help payload
+#### Help payload
 
 When `LocalizedMessage.message` doesn’t provide the user sufficient
 context or actionable next steps, or if there are multiple points of