用途
本技能用于诊断和解决 Guidewire InsuranceSuite 中最常见的错误，主要面向 Cloud API 调用、Gosu 开发以及系统集成过程中出现的问题。
前置条件
- 可访问 Guidewire Cloud Console 日志
- 理解 HTTP 状态码
- 熟悉 Gosu 异常处理
HTTP 状态码参考
| 代码 | 含义 | 常见原因 | 解决方式 |
|---|---|---|---|
| 400 | Bad Request | JSON 格式错误、字段无效 | 检查请求体结构 |
| 401 | Unauthorized | 令牌无效或过期 | 刷新 OAuth 令牌 |
| 403 | Forbidden | 缺少 API 角色 | 在 GCC 中检查角色分配 |
| 404 | Not Found | 端点或 ID 无效 | 核对 URL 与资源 ID |
| 409 | Conflict | 并发修改 | 使用更新后的校验和重试 |
| 422 | Unprocessable | 违反业务规则 | 修正校验错误 |
| 429 | Too Many Requests | 超出速率限制 | 实现退避 |
| 500 | Server Error | 内部错误 | 检查服务器日志 |
| 503 | Service Unavailable | 维护或过载 | 带退避重试 |
常见校验错误码
| 代码 | 描述 | 示例 |
|---|---|---|
| required | 缺少必填字段 | accountHolder is required |
| invalid_format | 数据格式错误 | dateOfBirth must be ISO date |
| invalid_value | 值不在允许集合内 | state.code 'XX' not valid |
| range_exceeded | 值超出范围 | premium exceeds policy limit |
| duplicate | 实体重复 | Account number already exists |
| reference_not_found | 外键无效 | producerCode.id not found |
使用方式
步骤 1：识别错误类别
检查 HTTP 状态码和错误响应体，判断问题属于认证（401/403）、校验（422）、并发（409）还是限流（429）。
步骤 2：套用正确的修复模式
- 401：实现令牌自动刷新，提前 60 秒缓冲过期时间
- 403：在 GCC Identity & Access 中添加所需 API 角色，等待 5 分钟生效
- 409：使用校验和实现 GET-then-PATCH 循环重试
- 422：按字段和代码解析校验明细，逐项修复违规
步骤 3：处理 Gosu 专有异常
关键模式：使用空安全操作符（?., ?:）；修改实体前先将其加入 bundle；处理多结果查询时的 AtMostOneRow；在提交期间捕获 ValidationException。
步骤 4：处理集成错误
对外部服务使用熔断器；对消息队列投递使用指数退避重试（最多 3 次）；对数据库操作实现死锁检测。
如需详细代码实现（TypeScript、Gosu、错误包装器），可加载参考指南： Read(${CLAUDE_SKILL_DIR}/references/implementation-guide.md)
输出
- 识别并归类错误
- 套用相应修复模式
- 实现错误处理代码
错误处理
| 错误 | 原因 | 解决方案 |
|---|---|---|
| 令牌刷新循环 | 凭据无效 | 在 GCC 中核对 client ID/secret |
| 校验和不匹配 | 数据陈旧 | 更新前重新获取 |
| 校验级联 | 依赖字段 | 先修复根字段 |
| 死锁超时 | 锁争用 | 加入带退避的重试 |
资源
- Cloud API Error Reference
- Gosu Exception Handling
- Integration Troubleshooting
下一步
如需调试技巧，参见 guidewire-debug-bundle。
示例
- 基础用法：在标准项目设置中使用 guidewire common errors 的默认配置选项。
- 高级场景：为生产环境定制 guidewire common errors，支持多约束和团队特定需求。