错误代码

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

1 - 错误概述

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

Dapr 错误代码是标准化的字符串，适用于 Dapr API 中 HTTP 和 gRPC 请求的 80 多种常见错误。这些代码会：

• 在请求的 JSON 响应体中返回。
• 启用后，会在运行时的调试级别日志中记录。
  • 如果您在 Kubernetes 中运行，错误代码会记录在 sidecar 中。
  • 如果您在自托管中运行，可以启用并查看调试日志。

错误格式

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 部分返回（如果存在）。 我们正在努力根据 更丰富的错误模型 来改进所有 gRPC 错误响应。没有对应 gRPC 代码的错误代码表示这些错误尚未更新到此模型。

演员 API

工作流 API

状态管理 API

配置 API

加密 API

密钥管理 API

发布/订阅和消息传递错误

对话 API

服务调用 / 直接消息传递 API

绑定 API

分布式锁 API

健康检查

通用

调度/作业 API

通用

下一步

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

3 - 处理 HTTP 错误代码

在向 Dapr 运行时发出的 HTTP 调用中，如果发生错误，响应体会返回一个错误的 JSON。该 JSON 包含错误代码和描述性错误信息。

{
    "errorCode": "ERR_STATE_GET",
    "message": "请求的状态键在状态存储中不存在。"
}

相关内容

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

4 - 处理 gRPC 错误代码

最初，错误是按照 标准 gRPC 错误模型 进行处理的。然而，为了提供更详细且信息丰富的错误消息，定义了一个增强的错误模型，与 gRPC 的 更丰富的错误模型 保持一致。

标准 gRPC 错误模型

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

标准 gRPC 错误响应示例：

ERROR:
  Code: InvalidArgument
  Message: 输入键/键前缀 'bad||keyname' 不能包含 '||'

更丰富的 gRPC 错误模型

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

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

ERROR:
  Code: InvalidArgument
  Message: 输入键/键前缀 'bad||keyname' 不能包含 '||'
  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": "输入键/键前缀 'bad||keyname' 不能包含 '||'"
    	    }
    	  ]
    	}

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

HTTP 错误响应示例：

{
    "errorCode": "ERR_MALFORMED_REQUEST",
    "message": "api error: code = InvalidArgument desc = 输入键/键前缀 'bad||keyname' 不能包含 '||'",
    "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 = 输入键/键前缀 'bad||keyname' 不能包含 '||'"
                }
            ]
        }
    ]
}

您可以在这里找到所有可能状态详细信息的规范。

相关链接

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