错误处理参考

错误处理先分类,再核对字段,最后决定动作。分类不清时反复重试通常无效,还会掩盖真正原因;把记录编号与发生时间留住,向目标主体说明问题时也能减少往返。记录是后续核对的基础,交接也更顺畅。

分类的作用与判断顺序

五类错误对应五个环节:接入、鉴权、寻址、调用、记录。分类清楚,处理对象随之明确;跨环节反复尝试,往往只是把同一个问题换一种方式再遇到。

判断顺序从错误说明开始,再核对标识与凭据,之后核对授权、端点与记录。顺序稳定,减少无效尝试,也便于向目标主体说明问题发生在哪一步。

同一问题多次出现时,保留每次的时间与记录编号,判断是否同一原因。不同原因合并处理,容易把已经解决的问题再次引入。

五类错误对照

每一类错误的核对字段不同。接入错误看材料与标识,鉴权错误看凭据与授权,寻址错误看标识与目标状态,调用错误看端点与字段,记录错误看时间与编号。

错误说明能定位环节时,直接按对应字段核对;说明不完整时,按顺序逐项排除,不跳过凭据与授权。

类型典型说明核对字段处理动作
接入错误材料不完整、标识重复主体信息、Agent 名称、标识补充材料或核对已有标识
鉴权错误凭据无效、授权过期调用方标识、凭据有效期、授权范围更新凭据或提交授权调整
寻址错误标识不存在、目标停用Agent 标识、目标状态核对标识或联系目标主体
调用错误端点不可达、字段不匹配端点、协议、请求字段核对端点与字段,联系目标主体
记录错误记录编号不存在请求时间、记录编号核对时间与编号是否对应

排查顺序与分界

逐项核对,不跳步。标识与凭据正确但端点不可达,属于调用环节;端点正常但授权不足,属于鉴权环节。分清环节后,处理对象也随之明确。

排查时保留每一步的核对结果。只记录最终动作,下一次出现同类错误仍要重新判断,交接也无法复现。

  1. 读取错误类型与错误说明,确认属于哪一类。
  2. 核对 Agent 标识与调用方标识是否正确。
  3. 核对凭据有效期与授权范围。
  4. 核对端点、协议与请求字段。
  5. 用记录编号查询本次调用记录,确认是否已处理。
  6. 按环节处理:补材料、换凭据、调授权、修端点或核对时间。

重试与幂等边界

寻址请求超时先核对记录编号,确认是否已经处理,再决定是否重新发起。超时不等同于失败,可能只是返回未及时到达;直接重试会增加重复处理的风险。

业务请求的超时与重试由调用方按业务规则处理。需要幂等时由调用方与目标 Agent 约定,平台不判断业务是否重复,也不回滚业务结果。

  • 鉴权失败不重试,先更新凭据或授权。
  • 标识不存在不重试,先核对拼写与目标状态。
  • 端点不可达不连续重试,先联系目标主体。
  • 记录编号不存在时核对时间,不用新请求替代查询。
  • 同一请求重复发起前,确认上一次的状态。
  • 业务侧需要幂等时,由调用方与目标约定识别方式。

反馈时需要提供的材料

反馈材料完整,核对次数会明显减少。说明错误类型与发生时间,附上标识与记录编号,接收方可以按同一路径复现;只描述现象,往往需要多轮往返。

涉及多个调用方时分别提供记录编号,避免把不同原因的失败合并处理。合并后处理动作无法对应到具体请求。

问题类型需要提供补充说明
调用失败错误类型、发生时间、Agent 标识、记录编号说明调用方与请求字段
鉴权问题调用方标识、凭据有效期、授权范围说明近期是否轮换或调整
端点问题端点、协议、请求字段说明是否近期变更
记录问题请求时间、记录编号、查询范围说明查询用途
安全事件异常时间、涉及标识、已采取动作先停用凭据并保留记录

涉及安全时的处理

怀疑凭据泄露、标识被冒用或出现异常调用时,先停用凭据,再保留记录并联系平台。没有记录就删除凭据或重建标识,后续无法判断异常请求的范围。

处置完成后复核凭据、回调与授权范围,确认没有遗留旧配置。涉及多个 Agent 时分别核对,避免只处理其中一个。

  1. 停用相关凭据,阻止继续调用。
  2. 保留调用记录与异常时间。
  3. 核对授权范围与回调地址。
  4. 按需重建凭据并完成一次调用核对。
  5. 复核其他 Agent 是否存在同类风险。

处理后的复核

复核时按原错误类型再核对一次对应字段,确认处理动作确实解决了该环节的问题。只看到请求成功就结束处理,同类错误可能在另一个调用方再次出现。

处理完成后重新发起一次请求,确认返回符合预期,再恢复常规调用。复核结果与处理动作一起记录,便于交接与后续判断。

同类错误再次出现时,先比对上次的处理记录,确认是否同一环节;不同环节的错误不合并处理,也不通过扩大授权范围绕过限制。

超时后可以直接重试吗
先按记录编号确认是否已处理,再决定是否重新发起。
凭据失效可以猜测原值吗
不能。停用后重新签发,明文只在创建时显示一次。
端点不可达要反复请求吗
不要。先联系目标主体核对端点与状态,再重新寻址。

让错误处理有据可查

先分类,再核对标识、凭据、授权与端点,保留记录编号与时间,按环节处理。

查看调用方式