分类的作用与判断顺序
五类错误对应五个环节:接入、鉴权、寻址、调用、记录。分类清楚,处理对象随之明确;跨环节反复尝试,往往只是把同一个问题换一种方式再遇到。
判断顺序从错误说明开始,再核对标识与凭据,之后核对授权、端点与记录。顺序稳定,减少无效尝试,也便于向目标主体说明问题发生在哪一步。
同一问题多次出现时,保留每次的时间与记录编号,判断是否同一原因。不同原因合并处理,容易把已经解决的问题再次引入。
五类错误对照
每一类错误的核对字段不同。接入错误看材料与标识,鉴权错误看凭据与授权,寻址错误看标识与目标状态,调用错误看端点与字段,记录错误看时间与编号。
错误说明能定位环节时,直接按对应字段核对;说明不完整时,按顺序逐项排除,不跳过凭据与授权。
| 类型 | 典型说明 | 核对字段 | 处理动作 |
|---|---|---|---|
| 接入错误 | 材料不完整、标识重复 | 主体信息、Agent 名称、标识 | 补充材料或核对已有标识 |
| 鉴权错误 | 凭据无效、授权过期 | 调用方标识、凭据有效期、授权范围 | 更新凭据或提交授权调整 |
| 寻址错误 | 标识不存在、目标停用 | Agent 标识、目标状态 | 核对标识或联系目标主体 |
| 调用错误 | 端点不可达、字段不匹配 | 端点、协议、请求字段 | 核对端点与字段,联系目标主体 |
| 记录错误 | 记录编号不存在 | 请求时间、记录编号 | 核对时间与编号是否对应 |
排查顺序与分界
逐项核对,不跳步。标识与凭据正确但端点不可达,属于调用环节;端点正常但授权不足,属于鉴权环节。分清环节后,处理对象也随之明确。
排查时保留每一步的核对结果。只记录最终动作,下一次出现同类错误仍要重新判断,交接也无法复现。
- 读取错误类型与错误说明,确认属于哪一类。
- 核对 Agent 标识与调用方标识是否正确。
- 核对凭据有效期与授权范围。
- 核对端点、协议与请求字段。
- 用记录编号查询本次调用记录,确认是否已处理。
- 按环节处理:补材料、换凭据、调授权、修端点或核对时间。
重试与幂等边界
寻址请求超时先核对记录编号,确认是否已经处理,再决定是否重新发起。超时不等同于失败,可能只是返回未及时到达;直接重试会增加重复处理的风险。
业务请求的超时与重试由调用方按业务规则处理。需要幂等时由调用方与目标 Agent 约定,平台不判断业务是否重复,也不回滚业务结果。
- 鉴权失败不重试,先更新凭据或授权。
- 标识不存在不重试,先核对拼写与目标状态。
- 端点不可达不连续重试,先联系目标主体。
- 记录编号不存在时核对时间,不用新请求替代查询。
- 同一请求重复发起前,确认上一次的状态。
- 业务侧需要幂等时,由调用方与目标约定识别方式。
反馈时需要提供的材料
反馈材料完整,核对次数会明显减少。说明错误类型与发生时间,附上标识与记录编号,接收方可以按同一路径复现;只描述现象,往往需要多轮往返。
涉及多个调用方时分别提供记录编号,避免把不同原因的失败合并处理。合并后处理动作无法对应到具体请求。
| 问题类型 | 需要提供 | 补充说明 |
|---|---|---|
| 调用失败 | 错误类型、发生时间、Agent 标识、记录编号 | 说明调用方与请求字段 |
| 鉴权问题 | 调用方标识、凭据有效期、授权范围 | 说明近期是否轮换或调整 |
| 端点问题 | 端点、协议、请求字段 | 说明是否近期变更 |
| 记录问题 | 请求时间、记录编号、查询范围 | 说明查询用途 |
| 安全事件 | 异常时间、涉及标识、已采取动作 | 先停用凭据并保留记录 |
涉及安全时的处理
怀疑凭据泄露、标识被冒用或出现异常调用时,先停用凭据,再保留记录并联系平台。没有记录就删除凭据或重建标识,后续无法判断异常请求的范围。
处置完成后复核凭据、回调与授权范围,确认没有遗留旧配置。涉及多个 Agent 时分别核对,避免只处理其中一个。
- 停用相关凭据,阻止继续调用。
- 保留调用记录与异常时间。
- 核对授权范围与回调地址。
- 按需重建凭据并完成一次调用核对。
- 复核其他 Agent 是否存在同类风险。
处理后的复核
复核时按原错误类型再核对一次对应字段,确认处理动作确实解决了该环节的问题。只看到请求成功就结束处理,同类错误可能在另一个调用方再次出现。
处理完成后重新发起一次请求,确认返回符合预期,再恢复常规调用。复核结果与处理动作一起记录,便于交接与后续判断。
同类错误再次出现时,先比对上次的处理记录,确认是否同一环节;不同环节的错误不合并处理,也不通过扩大授权范围绕过限制。
- 超时后可以直接重试吗
- 先按记录编号确认是否已处理,再决定是否重新发起。
- 凭据失效可以猜测原值吗
- 不能。停用后重新签发,明文只在创建时显示一次。
- 端点不可达要反复请求吗
- 不要。先联系目标主体核对端点与状态,再重新寻址。