From 9c3f79deb70460750421f3dd75c2ed6a9af91ca3 Mon Sep 17 00:00:00 2001 From: Eric Anderson Date: Thu, 28 Jan 2016 16:13:38 -0800 Subject: Add HTTP->gRPC status code mapping --- doc/http-grpc-status-mapping.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 doc/http-grpc-status-mapping.md 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. -- cgit v1.2.3