[AIP-193] Improve ErrorInfo and Details Rationale Documentation

[yordis]

Hi there, reading https://google.aip.dev/193#status-message-warning led me to seek clarifications and hopefully document the rationale.

---

ErrorInfo

The ErrorInfo message is the required way to send a machine-readable identifier. All error responses must include an ErrorInfo payload in the details field. Variable information should be included in the metadata field on ErrorInfo and must be included if it appears within an error message.

All error responses must include an ErrorInfo payload in the details field.

Therefore,

• What was the rationale for enforcing the ErrorInfo to be part of the details instead of a key directly at the top level of the error, for example:

{
  "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",
    "info": {
        "reason": "RESOURCE_AVAILABILITY",
        "domain": "compute.googleapis.com",
        "metadata": {}
    },
    "details": []
  }
}

Which is related to the following.

Note: ErrorInfo represents a special case. There must be exactly one ErrorInfo. It is required.

In that case, it makes more sense to move the ErrorInfo outside the details, which represents a list (instead of an object) and an unstructured payload that makes the situation a bit more tricky."

Having a key ensures that only one value exists, and having a strong type improves the specification.