错误与排查

错误按接入、鉴权、寻址、调用、记录五类处理。看到错误先判断类型,再核对标识、凭据、授权与端点,避免重复提交相同请求,也避免在原因不明时反复重试;记录编号用于还原本次请求。反馈时提供记录编号与发生时间。

五类错误

五类错误对应不同环节,处理方式也不同。先确认类型,再决定是补充材料、更新凭据、核对标识,还是联系目标主体;跨环节反复尝试通常不会解决问题。

类型常见原因处理方式
接入错误材料不完整、标识重复补充材料或核对已有标识
鉴权错误凭据无效、授权过期更新凭据或授权范围
寻址错误标识不存在、目标停用核对标识或联系目标主体
调用错误端点不可达、字段不匹配核对端点或请求字段
记录错误记录编号不存在核对请求时间与编号

排查顺序

排查从错误类型开始,再逐项核对对象与状态。顺序稳定可以减少反复尝试,也便于向目标主体说明问题;同一问题多次出现时,保留每次的时间与记录编号,判断是否为同一原因。

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

  1. 核对错误类型与错误说明。
  2. 核对 Agent 标识与调用方标识。
  3. 核对凭据有效期与授权范围。
  4. 核对端点、协议与请求字段。
  5. 使用记录编号查询本次调用记录。

处理原则

处理错误时不绕过限制,也不靠猜测恢复调用。需要变更时按登记与授权流程办理,变更后再核对记录;确认是目标 Agent 侧的问题时,联系目标主体处理。

需要目标主体配合时,说明错误类型、时间与记录编号,便于对方定位。对方完成调整后重新发起一次请求,确认结果后再恢复常规调用。

  • 凭据无效时重新签发,不尝试猜测原值。
  • 授权过期时提交授权调整,不绕过范围限制。
  • 标识不存在时核对拼写,或联系目标主体确认状态。
  • 端点不可达时联系目标主体,不反复请求。
  • 记录编号不存在时核对请求时间与编号是否对应。

提交反馈

反馈时提供错误类型、发生时间、Agent 标识、调用方标识与记录编号;鉴权问题补充凭据有效期与授权范围;端点问题补充协议与请求字段。材料完整可以减少往返核对,也便于判断问题是否已重复出现。

涉及多个调用方时,分别提供记录编号,避免把不同原因的失败合并处理。

涉及安全时

怀疑凭据泄露、标识被冒用或出现异常调用时,先停用凭据并保留调用记录,再联系平台。不要在没有记录的情况下删除凭据或重建标识,否则会影响判断;处置完成后按需重建凭据并核对调用。

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

查看安全说明

了解凭据生命周期、自助停用与重建,以及数据处理边界。

查看安全与合规