Skip to main content

错误与排障

按 API、MCP 和 A2A 的响应形态识别错误,并处理鉴权、参数、限流、任务和续传问题

先判断接入形态,再读取对应错误结构。API 的 HTTP 200 不一定代表业务成功,MCP 的工具错误不一定是 JSON-RPC 传输错误,A2A 的错误也可能出现在 SSE data 帧中。

API 错误

检索 API 返回以下业务错误时,HTTP 状态仍可为 200。响应包含 success: false、code、message 和空的 data 对象。网关或网络层失败时,请先检查实际 HTTP 状态和响应格式。
API 或 Agent 认证失败时,先检查 Authorization 是否为 API Key 原文、是否误加 Bearer,再检查 x-acs-date 是否为当前 UTC 时间的 ISO 8601 表示(精确到秒、以 Z 结尾),并在每次请求时重新生成。同时核对目标环境、x-acs-version: 2026-10-19 和 JSON 请求的 Content-Type: application/json。格式见接入认证。
{
  "code": 3404,
  "success": false,
  "message": "开放能力暂不可用,请稍后重试",
  "data": {}
}
业务码含义建议处理
400缺少必填的检索参数按目标接口文档补齐必填字段后重新发送
500检索服务内部错误保留请求标识与时间,按重试原则处理
1501参数、JSON、Schema 或请求大小不符合要求对照接口字段检查请求,不添加未定义字段
3400认证信息或访问权限无效检查 API Key 状态、目标能力访问权限和控制台接入配置
3403当前账号或成员资格不可用核对登录账号、成员状态和坐席
3404开放能力暂不可用稍后重试;持续失败时携请求时间和能力标识排查
3405请求过于频繁降低并发并采用退避重试,不假设未公布的 QPS 数值
3406请求已执行或正在执行检查原请求及调用记录,按重试原则处理原意图

管理 API Key 时的错误

业务码含义建议处理
3401Key 绑定状态或版本冲突刷新 API Key 管理页,核对当前状态后再操作
3402Key 绑定意图无效或已过期重新发起关联验证
3407需要已核验的阿里云网页登录账号使用已核验的阿里云账号登录后再操作

MCP 错误

认证或传输失败

法睿 MCP 在解析报文前拒绝请求时,会返回 JSON-RPC error,id 为 null。例如,入口参数异常可返回 HTTP 400,凭据问题可返回 401,身份不可用可返回 403,认证服务不可用可返回 503。以下是认证服务不可用的示例。
{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32001,
    "message": "[3404] 开放能力暂不可用,请稍后重试"
  }
}

工具执行失败

工具参数或业务执行失败时,响应通常仍包含 result,但 result.isError=true。文本内容使用 [业务码] 中文描述,不会套 API 的 success 信封:
{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[1501] 参数错误"
      }
    ],
    "isError": true
  }
}
调用方必须同时检查 JSON-RPC error 和 result.isError。tools/list 没有目标工具时不要猜测名称;工具调用失败不能当作一次成功业务结果处理。

A2A 错误

A2A 使用 JSON-RPC 2.0。先看响应的 Content-Type。普通 JSON 响应可直接读取 error。流式响应则从 SSE data 中读取错误,例如下方报文。
data: {"jsonrpc":"2.0","id":"req-001","error":{"code":-32015,"message":"Agent未激活或不存在","data":null}}
错误码含义建议处理
-32700JSON 解析失败检查请求体是否为合法 JSON
-32600 / -32601 / -32602请求无效、方法不存在或参数错误核对方法名和 params 结构
-32603Agent 内部错误保存请求 ID 和时间后排查,不依赖内部异常原文
-32001Task 不存在核对 taskId 及原任务归属
-32010相同 messageId 对应不同内容重试保持原报文;新任务使用新的 messageId
-32014断线续传已过期或不存在检查最后事件 ID;无法续传时按产品流程新建任务
-32015Agent 未激活或不存在核对 agentCode、Agent Card 和当前账号的访问权限
-32017认证失败检查 API Key 状态及其绑定的个人身份;tenantId 和 userId 由 API Key 补充,禁止在请求中传入
-32021Context 已有执行中的 Task取消或续订当前 Task,不并发占用同一 Context
-32022积分不足或订阅不可用在控制台检查额度和订阅状态
-32023Context 已关闭新建会话,不复用已结束的 contextId

提交排障信息前

  1. 记录接入形态、请求 ID、调用时间、精确路径、工具名或 agentCode、业务码或 JSON-RPC 错误码。
  2. API 保存请求与响应结果;MCP 保存工具名;A2A 保存 messageId、taskId、contextId 和最后收到的 SSE 事件 ID。
  3. 删除 API Key、完整认证请求头、Cookie、用户隐私和案件敏感材料。

查看常见问题

继续排查接入认证、工具发现、Agent 路由、计量与重试问题。