aboutsummaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
authorGravatar Abhishek Kumar <abhikumar@google.com>2016-09-15 10:33:55 -0700
committerGravatar GitHub <noreply@github.com>2016-09-15 10:33:55 -0700
commit500ca305b174a627abf3aa6511fea27d0ade4f36 (patch)
tree740d4c350ffe0f474141eed26dc7f3a1b1803ffc
parent78bb9a3ad7a40a5ba927671b3715dc95748cad9f (diff)
parent9c3f79deb70460750421f3dd75c2ed6a9af91ca3 (diff)
Merge pull request #4955 from ejona86/http-grpc-status-mapping
Add HTTP->gRPC status code mapping
-rw-r--r--doc/http-grpc-status-mapping.md30
1 files changed, 30 insertions, 0 deletions
diff --git a/doc/http-grpc-status-mapping.md b/doc/http-grpc-status-mapping.md
new file mode 100644
index 0000000000..928fe54420
--- /dev/null
+++ b/doc/http-grpc-status-mapping.md
@@ -0,0 +1,30 @@
+# HTTP to gRPC Status Code Mapping
+
+Since intermediaries are a common part of HTTP infrastructure some responses to
+gRPC requests may be received that do not include the grpc-status header. In
+some cases mapping error codes from an intermediary allows the gRPC client to
+behave more appropriately to the error situation without overloading the
+semantics of either error code.
+
+This table is to be used _only_ for clients that received a response that did
+not include grpc-status. If grpc-status was provided, it _must_ be used. Servers
+_must not_ use this table to determine an HTTP status code to use; the mappings
+are neither symmetric nor 1-to-1.
+
+| HTTP Status Code | gRPC Status Code |
+|----------------------------|--------------------|
+| 400 Bad Request | INTERNAL |
+| 401 Unauthorized | UNAUTHENTICATED |
+| 403 Forbidden | PERMISSION\_DENIED |
+| 404 Not Found | UNIMPLEMENTED |
+| 429 Too Many Requests | UNAVAILABLE |
+| 502 Bad Gateway | UNAVAILABLE |
+| 503 Service Unavailable | UNAVAILABLE |
+| 504 Gateway Timeout | UNAVAILABLE |
+| _All other codes_ | UNKNOWN |
+
+Technically, 1xx should have the entire header skipped and a subsequent header
+be read. See RFC 7540 ยง8.1.
+
+200 is UNKNOWN because there should be a grpc-status in case of truly OK
+response.