# Fabric 错误码与重试策略 v1

## 1) 统一错误响应结构
所有非 2xx 响应建议返回：

```json
{
  "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`