按 API、MCP 和 A2A 的响应形态识别错误,并处理鉴权、参数、限流、任务和续传问题
先判断接入形态,再读取对应错误结构。API 的 HTTP 200 不一定代表业务成功,MCP 的工具错误不一定是 JSON-RPC 传输错误,A2A 的错误也可能出现在 SSE
检索 API 返回以下业务错误时,HTTP 状态仍可为 200。响应包含
法睿 MCP 在解析报文前拒绝请求时,会返回 JSON-RPC
工具参数或业务执行失败时,响应通常仍包含
A2A 使用 JSON-RPC 2.0。先看响应的
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。格式见接入认证。管理 API Key 时的错误
| 业务码 | 含义 | 建议处理 |
|---|---|---|
3401 | Key 绑定状态或版本冲突 | 刷新 API Key 管理页,核对当前状态后再操作 |
3402 | Key 绑定意图无效或已过期 | 重新发起关联验证 |
3407 | 需要已核验的阿里云网页登录账号 | 使用已核验的阿里云账号登录后再操作 |
MCP 错误
认证或传输失败
法睿 MCP 在解析报文前拒绝请求时,会返回 JSON-RPC error,id 为 null。例如,入口参数异常可返回 HTTP 400,凭据问题可返回 401,身份不可用可返回 403,认证服务不可用可返回 503。以下是认证服务不可用的示例。
工具执行失败
工具参数或业务执行失败时,响应通常仍包含 result,但 result.isError=true。文本内容使用 [业务码] 中文描述,不会套 API 的 success 信封:
调用方必须同时检查 JSON-RPC
error 和 result.isError。tools/list 没有目标工具时不要猜测名称;工具调用失败不能当作一次成功业务结果处理。A2A 错误
A2A 使用 JSON-RPC 2.0。先看响应的 Content-Type。普通 JSON 响应可直接读取 error。流式响应则从 SSE data 中读取错误,例如下方报文。
| 错误码 | 含义 | 建议处理 |
|---|---|---|
-32700 | JSON 解析失败 | 检查请求体是否为合法 JSON |
-32600 / -32601 / -32602 | 请求无效、方法不存在或参数错误 | 核对方法名和 params 结构 |
-32603 | Agent 内部错误 | 保存请求 ID 和时间后排查,不依赖内部异常原文 |
-32001 | Task 不存在 | 核对 taskId 及原任务归属 |
-32010 | 相同 messageId 对应不同内容 | 重试保持原报文;新任务使用新的 messageId |
-32014 | 断线续传已过期或不存在 | 检查最后事件 ID;无法续传时按产品流程新建任务 |
-32015 | Agent 未激活或不存在 | 核对 agentCode、Agent Card 和当前账号的访问权限 |
-32017 | 认证失败 | 检查 API Key 状态及其绑定的个人身份;tenantId 和 userId 由 API Key 补充,禁止在请求中传入 |
-32021 | Context 已有执行中的 Task | 取消或续订当前 Task,不并发占用同一 Context |
-32022 | 积分不足或订阅不可用 | 在控制台检查额度和订阅状态 |
-32023 | Context 已关闭 | 新建会话,不复用已结束的 contextId |
提交排障信息前
- 记录接入形态、请求 ID、调用时间、精确路径、工具名或
agentCode、业务码或 JSON-RPC 错误码。 - API 保存请求与响应结果;MCP 保存工具名;A2A 保存
messageId、taskId、contextId和最后收到的 SSE 事件 ID。 - 删除 API Key、完整认证请求头、Cookie、用户隐私和案件敏感材料。
查看常见问题
继续排查接入认证、工具发现、Agent 路由、计量与重试问题。