Fabric/docs/error-codes-and-retry-policy-v1.md

Fabric 错误码与重试策略 v1

1) 统一错误响应结构

所有非 2xx 响应建议返回：

{
  "error": {
    "code": "FABRIC_XXX",
    "message": "human readable",
    "retryable": false
  }
}

可选字段：

• requestId: 请求追踪 id
• details: 参数错误详情

---

2) 业务错误码（v1）

通用

• FABRIC_BAD_REQUEST → 400（参数不合法）
• FABRIC_UNAUTHORIZED → 401（认证失败）
• FABRIC_FORBIDDEN → 403（鉴权/签名失败）
• FABRIC_NOT_FOUND → 404（资源不存在）
• FABRIC_CONFLICT → 409（资源冲突/重复）
• FABRIC_RATE_LIMITED → 429（限流）
• FABRIC_INTERNAL_ERROR → 500（服务内部错误）
• FABRIC_UNAVAILABLE → 503（依赖不可用）

Center↔Guild 协议

• FABRIC_HMAC_MISSING_HEADERS → 403
• FABRIC_HMAC_INVALID_SIGNATURE → 403
• FABRIC_HMAC_TIMESTAMP_EXPIRED → 403
• FABRIC_NODE_ID_CONFLICT → 409
• FABRIC_NODE_ENDPOINT_CONFLICT → 409

Messaging

• FABRIC_EDIT_WINDOW_EXPIRED → 409
• FABRIC_IDEMPOTENCY_REPLAY → 200（命中幂等缓存，非错误）

---

3) 重试策略（客户端/插件侧）

可重试（指数退避）

• HTTP: 429, 500, 502, 503, 504
• 网络异常：超时/连接重置/临时 DNS 故障

不可重试

• HTTP: 400, 401, 403, 404, 409（除非业务明确允许）

退避规则

• 基础间隔：1s
• 退避序列：1s / 2s / 4s / 8s / 16s
• 最大重试次数：5
• 加抖动：±20%
• 若有 Retry-After：优先按 Retry-After

---

4) 幂等与重试配合

• 写接口重试必须带 Idempotency-Key
• 同 key 重放返回首次响应，避免重复写入
• 幂等记录建议至少保留 24h

---

5) 服务端落地建议

• 网关/中间件统一异常映射为标准 error.code
• 在日志中记录：error.code、requestId、status
• 对 429/503 返回 Retry-After