Specification update for error code HTTP status

The RFC for this protocol change is open for voting as #148.

This PR proposes updating the Connect specification to correct the following error code to HTTP status mappings. The new status codes map closer to the intended HTTP semantics and better align with the RPC ecosystem of codes, specifically those defined in google/protobuf/code.proto.

Code	Current HTTP Status	Proposed HTTP Status
cancelled	408 Request Timeout	499 Client Closed Request
deadline_exceeded	408 Request Timeout	504 Gateway Timeout
failed_precondition	412 Precondition Failed	400 Bad Request
unimplemented	404 Not Found	501 Not Implemented

Reasons for proposed changes

408 Request Timeout

The 408 HTTP status is not suitable for RPC errors. Current cancelled and deadline_exceeded aren’t applicable as the request body was not timed out. Additionally, the definition defines the client MAY repeat the request which is not the intended behaviour of either code.

412 Precondition Failed

The 412 HTTP status indicates that HTTP headers specified in the request code, such as If-Unmodified-Since or If-None-Match, were used to conditionally apply the request. This isn’t the defined behaviour of failed_precondition which states the system state is not valid for the request and is unrelated to header values.

404 Not Found

The 404 HTTP status is used to indicate the resource doesn’t exist or the server doesn’t want to disclose the existence. For unimplemented a 501 Not Implemented is more applicable as that states that it’s the server that does not support the functionality required to fulfill the request not a resource issue.

499 Client Closed Request

The 499 HTTP status is a special case of the 502 Bad Gateway status code. It is adopted from the Nginx’s extended definition of 4XX errors to handle client errors. It indicates the client closed the connection whilst the server was still processing the request which aligns with the canceled error codes intent.

Impact

The proposed changes will necessitate updates in each implementation. Fortunately, all existing ConnectRPC organization libraries decode error codes from the response body, irrespective of the HTTP status on valid payloads. This behavior ensures backward compatibility, allowing the libraries to seamlessly accommodate the newly specified HTTP statuses without any adverse effects.

Resolves #122

connectrpc / connectrpc.com