故障码作用
故障码按失败位置划分:请求格式、凭据、权限、路由、频率、信源响应和信源超时各有对应编码。编码稳定,便于调用方按类型处理,也便于服务方分流排查。
故障码只描述网关侧的处理结果。同一个故障码可能由不同原因引起,定位时仍需结合请求编号和审计记录,不宜只看编码就下结论。
编码按失败位置分组,调用方可以据此判断应当修改请求、更新凭据还是联系信源方。分组方式在接入说明中保持一致。
故障码
编码与含义保持稳定,处理动作按类型给出。
编码含义与处理动作一一对应,遇到未列出的编码,按请求编号查询审计记录并向服务方反馈。
| 故障码 | 含义 | 处理动作 |
|---|---|---|
| GW-400 | 请求格式错误 | 核对字段、请求体和协议版本 |
| GW-401 | 凭据缺失或无效 | 更新凭据后重新提交 |
| GW-403 | 无权限 | 核对调用方、信源和字段授权 |
| GW-404 | 路由键不存在 | 核对路由键和信源登记 |
| GW-409 | 请求编号重复 | 使用原请求结果,不重复提交 |
| GW-429 | 请求过于频繁 | 按业务规则降低请求频率 |
| GW-502 | 信源返回错误 | 保留信源响应并记录 |
| GW-504 | 信源超时 | 检查信源端点和网络链路 |
排查顺序
按顺序核对,可以避免在未验证的环节反复修改配置。
顺序从调用方一侧开始,逐步向信源一侧推进。每一步只验证一个环节,避免同时修改多处配置。
- 记录故障码和请求编号。
- 核对调用方和凭据。
- 核对路由键和信源状态。
- 核对信源响应和网络链路。
- 需要时切换备选信源,并写入记录。
与信源错误的边界
故障码只说明网关侧的处理结果,不代替信源业务错误。信源返回的业务错误由调用方按业务规则处理。
信源超时与信源返回错误需要区分:前者关注端点和链路是否可达,后者需要查看信源响应内容。两者都不由网关改写。
网关不把信源业务错误改写成自己的故障码,也不替调用方判断业务是否成功。调用方按信源返回内容处理业务结果。
报障材料
材料完整可以缩短定位时间,涉及安全事件时先控制影响再排查。
材料按事项整理,一次提交完整信息,可以减少往返确认。涉及安全事件时,先控制凭据和访问范围。
服务方按故障码和记录分流,属于信源侧的问题转由信源方核对。
- 故障码、请求编号和发生时间。
- 调用方标识、凭据类型和授权范围。
- 路由键、目标信源和切换记录。
- 涉及的协议版本和网关节点。
- 安全事件先暂停相关凭据,保留审计记录并联系服务方。