Merge pull request #30 from ctoomey/error-model

Advanced error modeling

content/docs/guides/error.md

@@ -7,7 +7,7 @@ description: |
 
 <div id="toc" class="toc mobile-toc"></div>
 
-### Error model
+### Standard error model
 
 As you'll have seen in our concepts document and examples, when a gRPC call
 completes successfully the server returns an `OK` status to the client
@@ -18,6 +18,55 @@ If an error occurs, gRPC returns one of its error status codes instead, with an
 optional string error message that provides further details about what happened.
 Error information is available to gRPC clients in all supported languages.
 
+### Richer error model
+
+The error model described above is the official gRPC error model,
+is supported by all gRPC client/server libraries, and is independent of
+the gRPC data format (whether protocol buffers or something else). You
+may have noticed that it's quite limited and doesn't include the
+ability to communicate error details.
+
+If you're using protocol buffers as your data format, however, you may
+wish to consider using the the richer error model developed and used
+by Google as described
+[here](https://cloud.google.com/apis/design/errors#error_model). This
+model enables servers to return and clients to consume additional
+error details expressed as one or more protobuf messages. It further
+specifies a [standard set of error message
+types](https://github.com/googleapis/googleapis/blob/master/google/rpc/error_details.proto)
+to cover the most common needs (such as invalid parameters, quota
+violations, and stack traces). The protobuf binary encoding of this
+extra error information is provided as trailing metadata in the
+response.
+
+This richer error model is already supported in the C++, Go, Java,
+Python, and Ruby libraries, and at least the grpc-web and Node.js
+libraries have open issues requesting it. Other language libraries may
+add support in the future if there's demand, so check their github
+repos if interested. Note however that the grpc-core library written
+in C will not likely ever support it since it is purposely data format
+agnostic.
+
+You could use a similar approach (put error details in trailing
+response metadata) if you're not using protocol buffers, but you'd
+likely need to find or develop library support for accessing this data
+in order to make practical use of it in your APIs.
+
+There are important considerations to be aware of when deciding whether to
+use such an extended error model, however, including:
+
+  * library implementations of the extended error model may not be consistent
+across languages in terms of requirements for and expectations of the error
+details payload
+  * existing proxies, loggers, and other standard HTTP request
+processors don't have visibility into the error details and thus
+wouldn't be able to leverage them for monitoring or other purposes
+  * additional error detail in the trailers interferes with head-of-line
+blocking, and will decrease HTTP/2 header compression efficiency due to
+more frequent cache misses
+  * larger error detail payloads may run into protocol limits (like
+max headers size), effectively losing the original error
+
 ### Error status codes
 
 Errors are raised by gRPC under various circumstances, from network failures to