规范

第 10 章 错误处理

10.1 概述

TP 的错误处理设计原则：

  • 统一格式：所有错误使用 TPError 结构（详见 schema）
  • 类别前缀：错误码按层分类（ID、CTX、GOAL、SEC、NEG、TRA、VAL、VER、SYS）
  • 可恢复性分类：每个错误明确归类为「可重试」、「需协商」或「终态」
  • 关联请求：错误响应 MUST 通过 correlation_id 关联原请求

本章规定：

  • 错误码体系（§10.2）
  • TPError 结构与传输（§10.3）
  • 可恢复性分类（§10.4）
  • 错误恢复策略（§10.5）
  • 完整错误码索引（§10.6）

10.2 错误码体系

10.2.1 命名规则

错误码格式：TP-<CATEGORY><CODE>

  • TP- 前缀固定
  • <CATEGORY> 是 2-4 字母的层标识
  • <CODE> 是 3 位数字，从 001 开始

10.2.2 类别索引

类别来源章含义
ID§04身份辨识层错误
CTX§05共享语境层错误
GOAL§06目标协商层错误
SEC§07隐私与安全错误
NEG§08协议协商错误
TRA§09传输绑定错误
VAL跨层数据校验错误
VER跨层协议版本错误
SYS跨层系统/资源/超时错误

每章已列出该类别下的具体错误码。本章 §10.6 给出全集索引。

10.3 TPError 结构

10.3.1 字段约束

字段约束
error_codeMUST 符合 TP-<CAT><NUM> 格式
messageMUST 非空，MUST 是人类可读
detailsOPTIONAL；可携带结构化错误详情
recovery_suggestionsOPTIONAL；建议的恢复动作列表
correlation_idMUST 与原请求的 message_id 一致

10.3.2 message_type = error

错误响应的 MessageEnvelope.message_type MUST 为 "error"，payload MUST 为 TPError 对象。

{
  "tp_version": "1.0.0",
  "message_id": "<新 UUID>",
  "sender": { /* 错误返回方 */ },
  "receiver": { /* 原请求发送方 */ },
  "timestamp": "<ISO 8601>",
  "correlation_id": "<原请求 message_id>",
  "message_type": "error",
  "payload": {
    "error_code": "TP-CTX007",
    "message": "Time-limited access permission has expired",
    "details": {
      "context_id": "ctx:claim-2026-001",
      "resource_id": "res:diagnosis-2026-001",
      "expired_at": "2026-05-27T10:35:00.000Z"
    },
    "recovery_suggestions": [
      "Request a new credential with extended validity",
      "Re-establish a new SharedContext"
    ],
    "correlation_id": "<原请求 message_id>"
  },
  "signature": "<base64>"
}

10.3.3 错误信息本地化

message 字段 SHOULD 使用英语作为通用语；如需本地化，可在 details.localized_messages 中提供：

{
  "error_code": "TP-CTX007",
  "message": "Time-limited access permission has expired",
  "details": {
    "localized_messages": {
      "zh-CN": "时间限制权限已过期",
      "ja": "時間制限付き権限の有効期限が切れています"
    }
  }
}

10.4 可恢复性分类

10.4.1 三类错误

每个错误码 MUST 归入下列三类之一：

类别含义处理
Retriable临时性、可重试实现 SHOULD 自动重试（带退避）
Negotiable需要协商或调整后重试实现 SHOULD 调整请求后重试
Terminal终态错误，重试无意义实现 MUST 向上层报告失败

10.4.2 自动恢复指南

类别推荐重试策略最大重试次数
Retriable指数退避（initial 1s, factor 2, max 60s）5
Negotiable协商后立即重试一次1（每次协商）
Terminal不重试0

MessageEnvelope.trace_info SHOULD 记录重试次数。超过最大重试次数后 MUST 升级为 Terminal 错误。

10.5 错误恢复策略

10.5.1 身份层错误恢复

错误码类别恢复
TP-ID001Terminal修正 FayIdentity 后重新发起
TP-ID002Retriable重试（DNS / 网络问题）
TP-ID003Terminal检查签名实现
TP-ID004Retriable重新生成 message_id 后重试
TP-ID005Negotiable同步时钟后重试
TP-ID006Terminal修复客户端实现
TP-ID007-TP-ID010Negotiable重新申请人类原型授权

10.5.2 共享语境错误恢复

错误码类别恢复
TP-CTX001Terminalcontext 不存在，需重新建立
TP-CTX002Terminal非参与方，需重新创建 context 并加入
TP-CTX003Terminal非法状态转换，检查实现逻辑
TP-CTX004Terminal终态 context，需创建新 context
TP-CTX005-TP-CTX008Negotiable协商更新 ACL 或权限
TP-CTX011Terminal模式不允许，需重新创建为 collaborative_space
TP-CTX012-TP-CTX014Negotiable调整资源后重新挂载
TP-CTX020Negotiable应用冲突解决后重试
TP-CTX021Retriable重新同步

10.5.3 目标协商错误恢复

错误码类别恢复
TP-GOAL001Terminal修正 goal_id
TP-GOAL002Negotiable修正参数后重新提议
TP-GOAL003Terminal对端不支持该 goal_type
TP-GOAL004Terminal检查状态机实现
TP-GOAL005Terminal协商已超限，重启会话
TP-GOAL006-TP-GOAL009Negotiable修正 schema 或输出后重试
TP-GOAL010Terminal修正 DAG 后重新提议
TP-GOAL011Terminal父级取消，需重新规划
TP-GOAL012Negotiable调整约束或重新协商
TP-GOAL020-TP-GOAL022Negotiable缩减咨询链或重试

10.5.4 安全错误恢复

错误码类别恢复
TP-SEC001-TP-SEC003Terminal加密参数错误，检查实现
TP-SEC004Terminal签名错误，检查密钥
TP-SEC005Terminal字段不可披露
TP-SEC010-TP-SEC014Negotiable重新申请凭证
TP-SEC011Terminal凭证已撤销
TP-SEC020Terminal审计写入失败，安全策略要求阻止操作
TP-SEC030Terminal密钥已撤销，需轮换

10.5.5 协议协商错误恢复

错误码类别恢复
TP-NEG001-TP-NEG002Terminal修正候选列表后重试
TP-NEG003Negotiable增加候选传输方式
TP-NEG004Terminal安全级别冲突，无法协作
TP-NEG005-TP-NEG006Negotiable降级到 tier_3 重试
TP-NEG010-TP-NEG012Negotiable重新协商契约
TP-NEG020Retriable重试，超限后 Terminal

10.5.6 传输绑定错误恢复

错误码类别恢复
TP-TRA001Terminalhop 超限，需直连
TP-TRA002Retriable桥接器问题，重试
TP-TRA010-TP-TRA011Retriable网络超时，重试
TP-TRA020-TP-TRA021Negotiable协商更换传输方式
TP-TRA030-TP-TRA031TerminalPrompt 模式限制

10.6 完整错误码索引

身份辨识层（TP-ID0XX）

码类别描述
TP-ID001TerminalFayIdentity 字段缺失或格式错误
TP-ID002RetriableDID 公钥解析失败
TP-ID003Terminal签名验证失败
TP-ID004Retriable检测到重放
TP-ID005Negotiable时间戳超出窗口
TP-ID006Terminalpayload.identity 与 sender 不一致
TP-ID007NegotiableHostAuthorization 缺失
TP-ID008Negotiablefp_authorization_ref 无效
TP-ID009Negotiable操作超出 HostAuthorization 范围
TP-ID010Negotiable一致性级别声明不匹配

共享语境层（TP-CTX0XX）

码类别描述
TP-CTX001Terminalcontext_id 不存在
TP-CTX002Terminal非参与方
TP-CTX003Terminal非法状态转换
TP-CTX004Terminal终态执行操作
TP-CTX005Negotiabledefault_policy 拒绝
TP-CTX006Negotiableper_resource 权限不足
TP-CTX007Negotiabletime_limited 已过期
TP-CTX008Negotiablesuspended 状态写入
TP-CTX011Terminaldelegated_access 模式非拥有方写入
TP-CTX012Negotiable资源数据超大小限制
TP-CTX013Negotiable校验和不匹配
TP-CTX014Negotiable挂载点冲突
TP-CTX015Negotiable资源类型未声明
TP-CTX016Negotiable资源类型超出授权
TP-CTX020Negotiable同步冲突
TP-CTX021Retriable同步版本断层

目标协商层（TP-GOAL0XX）

码类别描述
TP-GOAL001Terminalgoal_id 不存在或重复
TP-GOAL002Negotiable参数不符合 schema
TP-GOAL003Terminalgoal_type 不支持
TP-GOAL004Terminal状态机非法转换
TP-GOAL005Terminal协商超过 10 次
TP-GOAL006Negotiableoutput_schema 缺失或无效
TP-GOAL007Terminalcontext_ref 不存在或非 active
TP-GOAL008Terminalcontext_ref="none" 但要求审计
TP-GOAL009Negotiableoutput 不符合 schema
TP-GOAL010TerminalDAG 循环依赖
TP-GOAL011Terminal父级取消
TP-GOAL012Negotiablerequired 约束不可满足
TP-GOAL020Terminal咨询链超过 5 跳
TP-GOAL021Negotiable缺少 authorization_scope
TP-GOAL022Retriable异步咨询超时

隐私与安全（TP-SEC0XX）

码类别描述
TP-SEC001Terminal加密算法不支持
TP-SEC002Terminal密钥协商失败
TP-SEC003Terminal解密失败
TP-SEC004Terminal载荷签名失败
TP-SEC005Terminal访问未披露字段
TP-SEC010Negotiable凭证不存在或过期
TP-SEC011Terminal凭证已撤销
TP-SEC012Terminalholder 不一致
TP-SEC013Negotiablescope 不含操作
TP-SEC014Negotiablescope 不含资源
TP-SEC020Terminal审计写入失败
TP-SEC030Terminal密钥已撤销

协议协商（TP-NEG0XX）

码类别描述
TP-NEG001Terminalcandidate_transports 为空
TP-NEG002Terminalcandidate_tiers 为空
TP-NEG003Negotiable无共同传输
TP-NEG004Terminal安全级别冲突
TP-NEG005Negotiabletier_1 capability 不一致
TP-NEG006Negotiabletier_2 不支持
TP-NEG010Negotiable缺少 contract_ref
TP-NEG011Negotiable契约不存在
TP-NEG012Negotiable契约已过期
TP-NEG020Retriable协商超时

传输绑定（TP-TRA0XX）

码类别描述
TP-TRA001Terminalhop 超过 5
TP-TRA002Retriable桥接失败
TP-TRA010RetriableWebSocket 心跳超时
TP-TRA011RetriableHTTP 超时
TP-TRA020NegotiableA2A 版本不兼容
TP-TRA021NegotiableMCP 工具不可用
TP-TRA030TerminalPrompt 中无 tp-envelope
TP-TRA031TerminalPrompt 不允许加密资源

数据校验（TP-VAL0XX）

码类别描述
TP-VAL001TerminalMessageType 枚举值未知
TP-VAL002Terminalpayload 不符合 schema
TP-VAL003Terminal含 additionalProperties: false 处出现未知字段
TP-VAL004Terminal必填字段缺失
TP-VAL005Terminal字段类型不匹配

协议版本（TP-VER0XX）

码类别描述
TP-VER001Terminal主版本不兼容
TP-VER002Negotiable次版本超前但可降级
TP-VER003Terminaltp_version 字符串非法

系统错误（TP-SYS0XX）

码类别描述
TP-SYS001Retriable内部超时
TP-SYS002Retriable资源耗尽（CPU/内存/连接数）
TP-SYS003Retriable上游依赖不可达（FP / SSP / 数据库）
TP-SYS004Retriable限流（rate limit）
TP-SYS005Terminal内部 bug（panic）