From 6998990686b014fcefcfcc4a62cd9e407a02ec9f Mon Sep 17 00:00:00 2001 From: Elena Kolevska Date: Tue, 19 Dec 2023 00:32:03 +0000 Subject: [PATCH 1/8] Adds a general docs/reference page for the richer error model Signed-off-by: Elena Kolevska --- .../content/en/reference/errors/_index.md | 89 +++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 daprdocs/content/en/reference/errors/_index.md diff --git a/daprdocs/content/en/reference/errors/_index.md b/daprdocs/content/en/reference/errors/_index.md new file mode 100644 index 00000000000..264f086f9c2 --- /dev/null +++ b/daprdocs/content/en/reference/errors/_index.md @@ -0,0 +1,89 @@ +--- +type: docs +title: Dapr Errors +linkTitle: "Dapr Errors" +weight: 700 +description: "Information on Dapr errors and how to handle them" +--- + +# Dapr Error Handling: Understanding the Error Models + +Initially, Dapr followed the standard gRPC error model. However, to provide more detailed and informative error messages, Dapr is transitioning to a richer error model as defined by gRPC. + +### Standard gRPC Error Model + +The [standard gRPC error model](https://grpc.io/docs/guides/error/#standard-error-model) is a straightforward approach to error reporting gRPC. Each error response includes an error code and an error message. The error codes are standardized and reflect common error conditions. + +Example of a Standard gRPC Error Response: +``` +ERROR: + Code: InvalidArgument + Message: input key/keyPrefix 'bad||keyname' can't contain '||' +``` + +### Richer gRPC Error Model + +The richer error model enhances the standard model by providing additional context and details about the error. This model includes the standard error code and message, along with a Details section that can contain various types of information, such as ErrorInfo, ResourceInfo, and BadRequest details. + +**Example of a Richer gRPC Error Response:** +``` +ERROR: + Code: InvalidArgument + Message: input key/keyPrefix 'bad||keyname' can't contain '||' + Details: + 1) { + "@type": "type.googleapis.com/google.rpc.ErrorInfo", + "domain": "dapr.io", + "reason": "DAPR_STATE_ILLEGAL_KEY" + } + 2) { + "@type": "type.googleapis.com/google.rpc.ResourceInfo", + "resourceName": "statestore", + "resourceType": "state" + } + 3) { + "@type": "type.googleapis.com/google.rpc.BadRequest", + "fieldViolations": [ + { + "field": "bad||keyname", + "description": "input key/keyPrefix 'bad||keyname' can't contain '||'" + } + ] + } +``` + +For HTTP clients, Dapr translates the gRPC error model to a similar structure in JSON format. The response includes an errorCode, a message, and a details array that mirrors the structure found in the richer gRPC model. + +**Example of an HTTP Error Response:** +```json +{ + "errorCode": "ERR_MALFORMED_REQUEST", + "message": "api error: code = InvalidArgument desc = input key/keyPrefix 'bad||keyname' can't contain '||'", + "details": [ + { + "@type": "type.googleapis.com/google.rpc.ErrorInfo", + "domain": "dapr.io", + "metadata": null, + "reason": "DAPR_STATE_ILLEGAL_KEY" + }, + { + "@type": "type.googleapis.com/google.rpc.ResourceInfo", + "description": "", + "owner": "", + "resource_name": "statestore", + "resource_type": "state" + }, + { + "@type": "type.googleapis.com/google.rpc.BadRequest", + "field_violations": [ + { + "field": "bad||keyname", + "description": "api error: code = InvalidArgument desc = input key/keyPrefix 'bad||keyname' can't contain '||'" + } + ] + } + ] +} +``` + +You can find the specification of all the possible status details [here](https://github.com/googleapis/googleapis/blob/master/google/rpc/error_details.proto). \ No newline at end of file From 992cd5be99071de61d0a9e4c10d4c5c9c29d52e0 Mon Sep 17 00:00:00 2001 From: Elena Kolevska Date: Tue, 19 Dec 2023 00:42:08 +0000 Subject: [PATCH 2/8] Adds a note about not all errors being enriched Signed-off-by: Elena Kolevska --- daprdocs/content/en/reference/errors/_index.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/daprdocs/content/en/reference/errors/_index.md b/daprdocs/content/en/reference/errors/_index.md index 264f086f9c2..58c4e7c8e78 100644 --- a/daprdocs/content/en/reference/errors/_index.md +++ b/daprdocs/content/en/reference/errors/_index.md @@ -8,7 +8,9 @@ description: "Information on Dapr errors and how to handle them" # Dapr Error Handling: Understanding the Error Models -Initially, Dapr followed the standard gRPC error model. However, to provide more detailed and informative error messages, Dapr is transitioning to a richer error model as defined by gRPC. +Initially, Dapr followed the standard gRPC error model. However, to provide more detailed and informative error messages, Dapr is gradually transitioning to a richer error model as defined by gRPC. + +> Not all Dapr errors have been converted to the richer gRPC error model. ### Standard gRPC Error Model @@ -25,6 +27,7 @@ ERROR: The richer error model enhances the standard model by providing additional context and details about the error. This model includes the standard error code and message, along with a Details section that can contain various types of information, such as ErrorInfo, ResourceInfo, and BadRequest details. + **Example of a Richer gRPC Error Response:** ``` ERROR: From accbf7b1118c5b7a862549e0a0682ff67c401f0f Mon Sep 17 00:00:00 2001 From: Elena Kolevska Date: Wed, 10 Jan 2024 17:59:35 +0000 Subject: [PATCH 3/8] Apply suggestions from code review Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> Signed-off-by: Elena Kolevska --- daprdocs/content/en/reference/errors/_index.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/daprdocs/content/en/reference/errors/_index.md b/daprdocs/content/en/reference/errors/_index.md index 58c4e7c8e78..4731a7cc952 100644 --- a/daprdocs/content/en/reference/errors/_index.md +++ b/daprdocs/content/en/reference/errors/_index.md @@ -1,22 +1,24 @@ --- type: docs -title: Dapr Errors -linkTitle: "Dapr Errors" +title: Dapr errors +linkTitle: "Dapr errors" weight: 700 description: "Information on Dapr errors and how to handle them" --- -# Dapr Error Handling: Understanding the Error Models +## Dapr Error Handling: Understanding the Error Models Initially, Dapr followed the standard gRPC error model. However, to provide more detailed and informative error messages, Dapr is gradually transitioning to a richer error model as defined by gRPC. -> Not all Dapr errors have been converted to the richer gRPC error model. +{{% alert title="Note" color="primary" %}} +Not all Dapr errors have been converted to the richer gRPC error model. +{{% /alert %}} ### Standard gRPC Error Model The [standard gRPC error model](https://grpc.io/docs/guides/error/#standard-error-model) is a straightforward approach to error reporting gRPC. Each error response includes an error code and an error message. The error codes are standardized and reflect common error conditions. -Example of a Standard gRPC Error Response: +**Example of a Standard gRPC Error Response:** ``` ERROR: Code: InvalidArgument @@ -25,7 +27,7 @@ ERROR: ### Richer gRPC Error Model -The richer error model enhances the standard model by providing additional context and details about the error. This model includes the standard error code and message, along with a Details section that can contain various types of information, such as ErrorInfo, ResourceInfo, and BadRequest details. +The richer error model enhances the standard model by providing additional context and details about the error. This model includes the standard error code and message, along with a `Details` section that can contain various types of information, such as `ErrorInfo`, `ResourceInfo`, and `BadRequest` details. **Example of a Richer gRPC Error Response:** @@ -55,7 +57,7 @@ ERROR: } ``` -For HTTP clients, Dapr translates the gRPC error model to a similar structure in JSON format. The response includes an errorCode, a message, and a details array that mirrors the structure found in the richer gRPC model. +For HTTP clients, Dapr translates the gRPC error model to a similar structure in JSON format. The response includes an `errorCode`, a `message`, and a `details` array that mirrors the structure found in the richer gRPC model. **Example of an HTTP Error Response:** ```json From 3a676db51ab1c22326398fd452272c1b8b32255f Mon Sep 17 00:00:00 2001 From: Elena Kolevska Date: Fri, 12 Jan 2024 11:44:00 +0000 Subject: [PATCH 4/8] Apply suggestions from code review Co-authored-by: Mark Fussell Signed-off-by: Elena Kolevska --- daprdocs/content/en/reference/errors/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/reference/errors/_index.md b/daprdocs/content/en/reference/errors/_index.md index 4731a7cc952..c73d8136887 100644 --- a/daprdocs/content/en/reference/errors/_index.md +++ b/daprdocs/content/en/reference/errors/_index.md @@ -16,7 +16,7 @@ Not all Dapr errors have been converted to the richer gRPC error model. ### Standard gRPC Error Model -The [standard gRPC error model](https://grpc.io/docs/guides/error/#standard-error-model) is a straightforward approach to error reporting gRPC. Each error response includes an error code and an error message. The error codes are standardized and reflect common error conditions. +The [standard gRPC error model](https://grpc.io/docs/guides/error/#standard-error-model) is an approach to error reporting in gRPC. Each error response includes an error code and an error message. The error codes are standardized and reflect common error conditions. **Example of a Standard gRPC Error Response:** ``` From d71bd4b81c3b1583c1166c18f32f072c17d3f28b Mon Sep 17 00:00:00 2001 From: Elena Kolevska Date: Tue, 23 Jan 2024 15:55:41 +0000 Subject: [PATCH 5/8] Apply suggestions from code review Signed-off-by: Elena Kolevska --- daprdocs/content/en/reference/errors/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/reference/errors/_index.md b/daprdocs/content/en/reference/errors/_index.md index c73d8136887..54ce54cd696 100644 --- a/daprdocs/content/en/reference/errors/_index.md +++ b/daprdocs/content/en/reference/errors/_index.md @@ -8,7 +8,7 @@ description: "Information on Dapr errors and how to handle them" ## Dapr Error Handling: Understanding the Error Models -Initially, Dapr followed the standard gRPC error model. However, to provide more detailed and informative error messages, Dapr is gradually transitioning to a richer error model as defined by gRPC. +Initially, errors followed the [Standard gRPC error model](https://grpc.io/docs/guides/error/#standard-error-model). However, to provide more detailed and informative error messages, an enhanced error model has been defined which aligns with the gRPC [Richer error model](https://grpc.io/docs/guides/error/#richer-error-model). {{% alert title="Note" color="primary" %}} Not all Dapr errors have been converted to the richer gRPC error model. From e16d22f79a44a96d750ee5ec2cebb9dec8b8d098 Mon Sep 17 00:00:00 2001 From: Elena Kolevska Date: Tue, 23 Jan 2024 16:13:36 +0000 Subject: [PATCH 6/8] Small fixes after review Signed-off-by: Elena Kolevska --- daprdocs/content/en/reference/errors/_index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/daprdocs/content/en/reference/errors/_index.md b/daprdocs/content/en/reference/errors/_index.md index 54ce54cd696..1411655af33 100644 --- a/daprdocs/content/en/reference/errors/_index.md +++ b/daprdocs/content/en/reference/errors/_index.md @@ -6,7 +6,7 @@ weight: 700 description: "Information on Dapr errors and how to handle them" --- -## Dapr Error Handling: Understanding the Error Models +## Error handling: Understanding errors model and reporting Initially, errors followed the [Standard gRPC error model](https://grpc.io/docs/guides/error/#standard-error-model). However, to provide more detailed and informative error messages, an enhanced error model has been defined which aligns with the gRPC [Richer error model](https://grpc.io/docs/guides/error/#richer-error-model). @@ -59,7 +59,7 @@ ERROR: For HTTP clients, Dapr translates the gRPC error model to a similar structure in JSON format. The response includes an `errorCode`, a `message`, and a `details` array that mirrors the structure found in the richer gRPC model. -**Example of an HTTP Error Response:** +**Example of an HTTP error response:** ```json { "errorCode": "ERR_MALFORMED_REQUEST", From 63858ae8e297b8aa232f08320c0eca5e1c4029fb Mon Sep 17 00:00:00 2001 From: Elena Kolevska Date: Thu, 25 Jan 2024 16:11:29 +0000 Subject: [PATCH 7/8] Small update Signed-off-by: Elena Kolevska --- daprdocs/content/en/reference/errors/_index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/daprdocs/content/en/reference/errors/_index.md b/daprdocs/content/en/reference/errors/_index.md index 1411655af33..dbe2d487453 100644 --- a/daprdocs/content/en/reference/errors/_index.md +++ b/daprdocs/content/en/reference/errors/_index.md @@ -16,7 +16,7 @@ Not all Dapr errors have been converted to the richer gRPC error model. ### Standard gRPC Error Model -The [standard gRPC error model](https://grpc.io/docs/guides/error/#standard-error-model) is an approach to error reporting in gRPC. Each error response includes an error code and an error message. The error codes are standardized and reflect common error conditions. +The [Standard gRPC error model](https://grpc.io/docs/guides/error/#standard-error-model) is an approach to error reporting in gRPC. Each error response includes an error code and an error message. The error codes are standardized and reflect common error conditions. **Example of a Standard gRPC Error Response:** ``` @@ -27,7 +27,7 @@ ERROR: ### Richer gRPC Error Model -The richer error model enhances the standard model by providing additional context and details about the error. This model includes the standard error code and message, along with a `Details` section that can contain various types of information, such as `ErrorInfo`, `ResourceInfo`, and `BadRequest` details. +The [Richer gRPC error model](https://grpc.io/docs/guides/error/#richer-error-model) extends the standard error model by providing additional context and details about the error. This model includes the standard error `code` and `message`, along with a `details` section that can contain various types of information, such as `ErrorInfo`, `ResourceInfo`, and `BadRequest` details. **Example of a Richer gRPC Error Response:** From 29fc98bc145a4a8f762ca38ff9ade05c5a6f8b78 Mon Sep 17 00:00:00 2001 From: Elena Kolevska Date: Thu, 25 Jan 2024 21:21:43 +0000 Subject: [PATCH 8/8] Add related links Signed-off-by: Elena Kolevska --- daprdocs/content/en/reference/errors/_index.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/daprdocs/content/en/reference/errors/_index.md b/daprdocs/content/en/reference/errors/_index.md index dbe2d487453..35f685f7491 100644 --- a/daprdocs/content/en/reference/errors/_index.md +++ b/daprdocs/content/en/reference/errors/_index.md @@ -91,4 +91,9 @@ For HTTP clients, Dapr translates the gRPC error model to a similar structure in } ``` -You can find the specification of all the possible status details [here](https://github.com/googleapis/googleapis/blob/master/google/rpc/error_details.proto). \ No newline at end of file +You can find the specification of all the possible status details [here](https://github.com/googleapis/googleapis/blob/master/google/rpc/error_details.proto). + +## Related Links + +- [Authoring error codes](https://github.com/dapr/dapr/tree/master/pkg/api/errors) +- [Using error codes in the Go SDK](https://docs.dapr.io/developing-applications/sdks/go/go-client/#error-handling)