From b22f3cd3b20a922c74f3fd8a4355ea11fe7de643 Mon Sep 17 00:00:00 2001 From: Edward McFarlane Date: Wed, 31 Jan 2024 09:56:37 -0500 Subject: [PATCH 1/2] Correct HTTP Status mapping for Error Codes This proposes updating the ConnectRPC 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](https://buf.build/googleapis/googleapis/file/main:google/rpc/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 | --- docs/protocol.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/protocol.md b/docs/protocol.md index 8b4067c9..9e42f629 100644 --- a/docs/protocol.md +++ b/docs/protocol.md @@ -508,18 +508,18 @@ gRPC. Only the codes below are valid — there are no user-defined codes. | Code | HTTP Status | Description | | ---- | ----------- | ----------- | -| `canceled` | 408 Request Timeout | RPC canceled, usually by the caller. | +| `canceled` | 499 Client Closed Request | RPC canceled, usually by the caller. | | `unknown` | 500 Internal Server Error | Catch-all for errors of unclear origin and errors without a more appropriate code. | | `invalid_argument` | 400 Bad Request | Request is invalid, regardless of system state. | -| `deadline_exceeded` | 408 Request Timeout | Deadline expired before RPC could complete or before the client received the response. | +| `deadline_exceeded` | 504 Gateway Timeout | Deadline expired before RPC could complete or before the client received the response. | | `not_found` | 404 Not Found | User requested a resource (for example, a file or directory) that can't be found. | | `already_exists` | 409 Conflict | Caller attempted to create a resource that already exists. | | `permission_denied` | 403 Forbidden | Caller isn't authorized to perform the operation. | | `resource_exhausted` | 429 Too Many Requests | Operation can't be completed because some resource is exhausted. Use unavailable if the server is temporarily overloaded and the caller should retry later. | -| `failed_precondition` | 412 Precondition Failed | Operation can't be completed because the system isn't in the required state. | +| `failed_precondition` | 400 Bad Request | Operation can't be completed because the system isn't in the required state. | | `aborted` | 409 Conflict | The operation was aborted, often because of concurrency issues like a database transaction abort. | | `out_of_range` | 400 Bad Request | The operation was attempted past the valid range. | -| `unimplemented` | 404 Not Found | The operation isn't implemented, supported, or enabled. | +| `unimplemented` | 501 Not Implemented | The operation isn't implemented, supported, or enabled. | | `internal` | 500 Internal Server Error | An invariant expected by the underlying system has been broken. Reserved for serious errors. | | `unavailable` | 503 Service Unavailable | The service is currently unavailable, usually transiently. Clients should back off and retry idempotent operations. | | `data_loss` | 500 Internal Server Error | Unrecoverable data loss or corruption. | From aee3068dd72b4d9b10263d309d94362765b8733d Mon Sep 17 00:00:00 2001 From: Edward McFarlane Date: Thu, 1 Feb 2024 16:53:08 -0500 Subject: [PATCH 2/2] Reduce inferred error code mapping See https://github.com/grpc/grpc/blob/master/doc/http-grpc-status-mapping.md Inferred error codes are only for clients that received an invalid RPC response. Handlers must not use this mapping to determine which status code to use. They are intentionally conservative and are not symmetric. Clients should use the inferred code to handle the error condition. --- docs/protocol.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/docs/protocol.md b/docs/protocol.md index 9e42f629..9106df20 100644 --- a/docs/protocol.md +++ b/docs/protocol.md @@ -561,17 +561,11 @@ unknown or internal), Connect maps to the semantically-equivalent error code. | HTTP Status | Inferred Code | | ----------- | ------------- | -| 400 Bad Request | `invalid_argument` | +| 400 Bad Request | `internal` | | 401 Unauthorized | `unauthenticated` | | 403 Forbidden | `permission_denied` | | 404 Not Found | `unimplemented` | -| 408 Request Timeout | `deadline_exceeded` | -| 409 Conflict | `aborted` | -| 412 Precondition Failed | `failed_precondition` | -| 413 Payload Too Large | `resource_exhausted` | -| 415 Unsupported Media Type | `internal` | | 429 Too Many Requests | `unavailable` | -| 431 Request Header Fields Too Large | `resource_exhausted` | | 502 Bad Gateway | `unavailable` | | 503 Service Unavailable | `unavailable` | | 504 Gateway Timeout | `unavailable` |