A2A 错误码：JSON-RPC、gRPC 与 HTTP 映射

A2A 定义了九个专有错误，并把每个错误映射到各绑定的原生错误模型上。本页是速查表：找到您收到的错误，看它由什么触发，以及它在 JSON-RPC、gRPC 和 HTTP+JSON 中的样子。叙述性的说明见核心协议规范和协议绑定详解。已对照 A2A v1.0.1 核对。

无论哪种绑定，每个错误必须表达一个机器可读的错误码和一条人类可读的消息，还可以附带一组详情对象，每个对象都带有 @type 键。规范要求实现在适用时使用 google.rpc 的通用类型，例如 ErrorInfo 和 BadRequest。

九个 A2A 错误

错误	JSON-RPC	gRPC	HTTP	`ErrorInfo.reason`	触发条件
`TaskNotFoundError`	`-32001`	`NOT_FOUND`	`404`	`TASK_NOT_FOUND`	任务 ID 与现有的、可访问的任务不匹配：无效、过期或已被清理
`TaskNotCancelableError`	`-32002`	`FAILED_PRECONDITION`	`400`	`TASK_NOT_CANCELABLE`	请求取消的任务不在可取消状态，例如已处于终态
`PushNotificationNotSupportedError`	`-32003`	`FAILED_PRECONDITION`	`400`	`PUSH_NOTIFICATION_NOT_SUPPORTED`	使用了推送通知，但 `capabilities.pushNotifications` 为 `false`
`UnsupportedOperationError`	`-32004`	`FAILED_PRECONDITION`	`400`	`UNSUPPORTED_OPERATION`	该智能体不支持此操作或操作的某一方面
`ContentTypeNotSupportedError`	`-32005`	`INVALID_ARGUMENT`	`400`	`CONTENT_TYPE_NOT_SUPPORTED`	请求的 Part 中的媒体类型，或产物隐含的媒体类型，不被智能体或技能支持
`InvalidAgentResponseError`	`-32006`	`INTERNAL`	`500`	`INVALID_AGENT_RESPONSE`	智能体返回的响应不符合规范对该方法的要求
`ExtendedAgentCardNotConfiguredError`	`-32007`	`FAILED_PRECONDITION`	`400`	`EXTENDED_AGENT_CARD_NOT_CONFIGURED`	操作需要扩展 Agent Card，但没有配置
`ExtensionSupportRequiredError`	`-32008`	`FAILED_PRECONDITION`	`400`	`EXTENSION_SUPPORT_REQUIRED`	服务器需要卡片中标记为 `required: true` 的扩展，而客户端没有声明支持
`VersionNotSupportedError`	`-32009`	`FAILED_PRECONDITION`	`400`	`VERSION_NOT_SUPPORTED`	`A2A-Version` 服务参数指定的版本不被该智能体支持

规范对 reason 的规则是：错误名称去掉 Error 后缀并转成 UPPER_SNAKE_CASE，domain 始终为 a2a-protocol.org。规范明确写出了 TASK_NOT_FOUND 和 TASK_NOT_CANCELABLE，该列的其余取值由同一规则推出。

区分状态相同的错误

九个错误中有七个共用 HTTP 400，六个共用 gRPC FAILED_PRECONDITION，仅凭状态无法确定是哪个错误。因此规范要求在 gRPC 和 HTTP+JSON 绑定中，每个 A2A 专有错误都带上 google.rpc.ErrorInfo 详情：请读取其中的 reason。JSON-RPC 中数字 code 本身就是唯一的。

哪个操作返回哪个错误

规范按操作列出了这些错误。不与单个操作绑定的错误列在表格下方。

操作	规范列出的错误
`SendMessage`	`ContentTypeNotSupportedError`、`UnsupportedOperationError`（任务已处于终态）、`TaskNotFoundError`
`SendStreamingMessage`	`UnsupportedOperationError`（不支持流式，或任务已处于终态）、`ContentTypeNotSupportedError`、`TaskNotFoundError`
`GetTask`	`TaskNotFoundError`
`ListTasks`	没有该操作特有的错误
`CancelTask`	`TaskNotCancelableError`、`TaskNotFoundError`
`SubscribeToTask`	`UnsupportedOperationError`（不支持流式，或任务已处于终态）、`TaskNotFoundError`
创建、获取、列出、删除推送通知配置	`PushNotificationNotSupportedError`、`TaskNotFoundError`（任务不存在；获取时指配置不存在）
`GetExtendedAgentCard`	`UnsupportedOperationError`（智能体不支持扩展卡片）、`ExtendedAgentCardNotConfiguredError`（声明了支持但没有配置卡片）

不与单个操作绑定的错误：

VersionNotSupportedError：A2A-Version 不被智能体支持的任何请求。
ExtensionSupportRequiredError：客户端没有声明支持的必需扩展。
InvalidAgentResponseError：规范没有给出针对具体操作的触发条件。

取消操作是幂等的，但任务被取消并清理之后，重复的取消请求可以返回 TaskNotFoundError。

九个之外

与 A2A 无关的失败使用各绑定的原生错误码。规范把它们分为五类：

类别	HTTP	gRPC	JSON-RPC
认证	`401`	`UNAUTHENTICATED`	自定义错误
授权	`403`	`PERMISSION_DENIED`	自定义错误
校验	`400`	`INVALID_ARGUMENT`	`-32602`
资源	`404`	`NOT_FOUND`	自定义（A2A 专有）错误
系统	`500` 或 `503`	`INTERNAL` 或 `UNAVAILABLE`	`-32603`

服务器不得向未获授权访问某资源的客户端透露该资源是否存在，也不应区分"不存在"和"未授权"。

JSON-RPC 另有五个标准错误码。A2A 专有错误码位于 -32001 至 -32099 区间。

错误码	名称	标准消息
`-32700`	`JSONParseError`	“Invalid JSON payload”
`-32600`	`InvalidRequestError`	“Request payload validation error”
`-32601`	`MethodNotFoundError`	“Method not found”
`-32602`	`InvalidParamsError`	“Invalid parameters”
`-32603`	`InternalError`	“Internal error”

同一个错误在各绑定中的样子

三个要素在各绑定中的对应关系不同：

要素	JSON-RPC	gRPC	HTTP+JSON
错误码	`error.code`（数字）	`status.code`	HTTP 状态和 `error.code`
消息	`error.message`	`status.message`	`error.message`
详情	`error.data`（数组）	`status.details`	`error.details`（数组）

JSON-RPC 把详情列表叫作 data，另外两种叫 details。下面是规范自己给出的"任务未找到"错误示例。

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32001,
    "message": "Task not found",
    "data": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "TASK_NOT_FOUND",
        "domain": "a2a-protocol.org",
        "metadata": {
          "taskId": "nonexistent-task-id",
          "timestamp": "2025-11-09T10:30:00.000Z"
        }
      }
    ]
  }
}

gRPC

status {
  code: NOT_FOUND
  message: "Task with ID 'task-123' not found"
  details: [
    {
      type: "type.googleapis.com/google.rpc.ErrorInfo"
      reason: "TASK_NOT_FOUND"
      domain: "a2a-protocol.org"
      metadata: {
        task_id: "task-123"
        timestamp: "2025-11-09T10:30:00Z"
      }
    }
  ]
}

HTTP+JSON

HTTP/1.1 404 Not Found
Content-Type: application/a2a+json

{
  "error": {
    "code": 404,
    "status": "NOT_FOUND",
    "message": "The specified task ID does not exist or is not accessible",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "TASK_NOT_FOUND",
        "domain": "a2a-protocol.org",
        "metadata": {
          "taskId": "task-123",
          "timestamp": "2025-11-09T10:30:00.000Z"
        }
      }
    ]
  }
}

校验失败在同一位置使用 google.rpc.BadRequest。规范给出的示例是 message.parts 为空的请求，以字段违规的形式报告，描述为 “At least one part is required”。