错误码

• 1: 错误概述
• 2: 错误码参考指南
• 3: 处理 HTTP 错误代码
• 4: 处理 gRPC 错误码

1 - 错误概述

错误码是一个数字或字母数字代码，用于指示错误的性质，并在可能的情况下说明错误发生的原因。

Dapr 错误码是使用 Dapr API 进行 HTTP 和 gRPC 请求时 80 多种常见错误的标准化字符串。这些代码同时具备以下功能：

• 在请求的 JSON 响应体中返回。
• 启用后，在运行时日志中以 debug 级别记录。
  • 如果在 Kubernetes 中运行，错误码会记录在边车中。
  • 如果在自托管模式下运行，你可以启用并运行 debug 日志。

错误格式

Dapr 错误码由前缀、类别和错误简写组成。例如：

一些最常见的返回错误包括：

• ERR_ACTOR_TIMER_CREATE
• ERR_PURGE_WORKFLOW
• ERR_STATE_STORE_NOT_FOUND
• ERR_HEALTH_NOT_READY

注意： 查看 Dapr 中的完整错误码列表。

状态存储未找到时返回的错误可能如下所示：

{
  "error": "Bad Request",
  "error_msg": "{\"errorCode\":\"ERR_STATE_STORE_NOT_FOUND\",\"message\":\"state store <name> is not found\",\"details\":[{\"@type\":\"type.googleapis.com/google.rpc.ErrorInfo\",\"domain\":\"dapr.io\",\"metadata\":{\"appID\":\"nodeapp\"},\"reason\":\"DAPR_STATE_NOT_FOUND\"}]}",
  "status": 400
}

返回的错误包含：

• 错误码：ERR_STATE_STORE_NOT_FOUND
• 描述问题的错误消息：state store <name> is not found
• 发生错误的应用程序 ID：nodeapp
• 错误原因：DAPR_STATE_NOT_FOUND

Dapr 错误码指标

指标帮助你查看运行时内部错误发生的具体时间。错误码指标通过 error_code_total 端点收集。该端点默认禁用。你可以通过在配置文件中使用 recordErrorCodes 字段来启用它。

演示

观看在 Diagrid Dapr v1.15 庆祝活动上呈现的演示，了解如何启用错误码指标以及如何处理运行时中返回的错误码。

下一步

2 - 错误码参考指南

以下表格列出了 Dapr 运行时返回的错误码。 错误码在 HTTP 请求的响应体中返回，或在 gRPC 状态响应的 ErrorInfo 部分中返回（如果存在）。 一项正在推进的工作是，根据 Richer Error Model 丰富所有 gRPC 错误响应。尚无对应 gRPC 代码的错误码表示这些错误尚未更新到此模型。

Actors API

工作流 API

状态管理 API

Configuration API

密码学 API

Secrets API

发布订阅和消息错误

对话 API

服务调用 / 直接消息 API

Bindings API

分布式锁 API

健康检查

通用

Scheduler/Jobs API

通用

后续步骤

• 处理 HTTP 错误码
• 处理 gRPC 错误码

3 - 处理 HTTP 错误代码

对于发往 Dapr 运行时的 HTTP 调用，当遇到错误时，会在响应正文中返回一个错误 JSON。该 JSON 包含一个错误代码和一条描述性错误消息。

{
    "errorCode": "ERR_STATE_GET",
    "message": "Requested state key does not exist in state store."
}

相关

• 错误代码参考列表
• 处理 gRPC 错误代码

4 - 处理 gRPC 错误码

最初，错误遵循标准 gRPC 错误模型。然而，为了提供更详细和更有信息量的错误消息，定义了一个增强的错误模型，该模型与 gRPC 更丰富的错误模型保持一致。

标准 gRPC 错误模型

标准 gRPC 错误模型是 gRPC 中的一种错误报告方法。每个错误响应包含一个错误码和一个错误消息。错误码是标准化的，反映了常见的错误条件。

标准 gRPC 错误响应示例：

ERROR:
  Code: InvalidArgument
  Message: input key/keyPrefix 'bad||keyname' can't contain '||'

更丰富的 gRPC 错误模型

更丰富的 gRPC 错误模型通过提供有关错误的额外上下文和详细信息来扩展标准错误模型。该模型包括标准的错误 code 和 message，以及一个 details 部分，其中可以包含各种类型的信息，例如 ErrorInfo、ResourceInfo 和 BadRequest 详细信息。

更丰富的 gRPC 错误响应示例：

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 '||'"
    	    }
    	  ]
    	}

对于 HTTP 客户端，Dapr 将 gRPC 错误模型转换为类似的 JSON 格式结构。响应包括一个 errorCode、一个 message 和一个 details 数组，该数组反映了在更丰富的 gRPC 模型中找到的结构。

HTTP 错误响应示例：

{
    "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 '||'"
                }
            ]
        }
    ]
}

你可以在这里找到所有可能的状态详情的规范。

相关链接

• 编写错误码
• 在 Go SDK 中使用错误码