AIP-193: Move JSON representation details to the bottom, and clarify

This is more of an informative section than anything else - API designers only need to know about it in order to understand the JSON response they might see from curl etc.

Author: jskeet

aip/general/0193.md

@@ -36,54 +36,6 @@ important to [set the right tone][writing-tone] when writing messages.
 
 ### Error Response
 
-#### JSON representation
-
-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": {
-    "code": 429,
-    "message": "The zone 'us-east1-a' does not have enough resources available to fulfill the request. Try a different zone, or try again later.",
-    "status": "RESOURCE_EXHAUSTED",
-    "details": [
-      {
-        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
-        "reason": "RESOURCE_AVAILABILITY",
-        "domain": "compute.googleapis.com",
-        "metadata": {
-          "zone": "us-east1-a",
-          "vmType": "e2-medium",
-          "attachment": "local-ssd=3,nvidia-t4=2",
-          "zonesWithCapacity": "us-central1-f,us-central1-c"
-        }
-      },
-      {
-        "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
-        "locale": "en-US",
-        "message": "An <e2-medium> VM instance with <local-ssd=3,nvidia-t4=2> is currently unavailable in the <us-east1-a> zone. Consider trying your request in the <us-central1-f,us-central1-c> 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."
-      },
-      {
-        "@type": "type.googleapis.com/google.rpc.Help",
-        "links": [
-          {
-            "description": "Additional information on this error",
-            "url": "https://cloud.google.com/compute/docs/resource-error"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
 #### google.rpc.Status
 
 Services must return a [`google.rpc.Status`][Status] message when an API
@@ -458,6 +410,85 @@ If the user does have proper permission, but the requested resource or
 parent does not exist, the service **must** error with `NOT_FOUND` (HTTP
 404).
 
+## HTTP/1.1+JSON representation
+
+When clients use HTTP/1.1 as per [AIP-127](./0127.md), the error information
+is returned in the body of the response, as a JSON object. For backward
+compatibility reasons, this does not map precisely to `google.rpc.Status`,
+but contains the same core information. The schema is defined in the following proto:
+
+```proto
+message Error {
+  message Status {
+    // The HTTP status code that corresponds to `google.rpc.Status.code`.
+    int32 code = 1;
+    // This corresponds to `google.rpc.Status.message`.
+    string message = 2;
+    // This is the enum version for `google.rpc.Status.code`.
+    google.rpc.Code status = 4;
+    // This corresponds to `google.rpc.Status.details`.
+    repeated google.protobuf.Any details = 5;
+  }
+
+  Status error = 1;
+}
+```
+
+The most important difference is that the `code` field in the JSON is an HTTP status code,
+*not* the direct value of `google.rpc.Status.code`. For example, a `google.rpc.Status`
+message with a `code` value of 5 would be mapped to an object including the following
+code-related fields (as well as the message, details etc):
+
+```json
+{
+  "error": {
+    "code": 404,          // The HTTP status code for "not found"
+    "status": "NOT_FOUND" // The name in google.rpc.Code for value 5
+  }
+}
+```
+
+The following JSON shows a fully populated HTTP/1.1+JSON representation of an error response.
+
+
+```json
+{
+  "error": {
+    "code": 429,
+    "message": "The zone 'us-east1-a' does not have enough resources available to fulfill the request. Try a different zone, or try again later.",
+    "status": "RESOURCE_EXHAUSTED",
+    "details": [
+      {
+        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
+        "reason": "RESOURCE_AVAILABILITY",
+        "domain": "compute.googleapis.com",
+        "metadata": {
+          "zone": "us-east1-a",
+          "vmType": "e2-medium",
+          "attachment": "local-ssd=3,nvidia-t4=2",
+          "zonesWithCapacity": "us-central1-f,us-central1-c"
+        }
+      },
+      {
+        "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
+        "locale": "en-US",
+        "message": "An <e2-medium> VM instance with <local-ssd=3,nvidia-t4=2> is currently unavailable in the <us-east1-a> zone. Consider trying your request in the <us-central1-f,us-central1-c> 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."
+      },
+      {
+        "@type": "type.googleapis.com/google.rpc.Help",
+        "links": [
+          {
+            "description": "Additional information on this error",
+            "url": "https://cloud.google.com/compute/docs/resource-error"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+
 ## Rationale
 
 ### Requiring ErrorInfo