From 3795aea2cb807a11409a534ba59992d5783b6550 Mon Sep 17 00:00:00 2001
From: nav <nav@mgr.hangman-lab.top>
Date: Tue, 12 May 2026 11:18:00 +0000
Subject: [PATCH] docs(protocol): define unified error codes and retry policy
 v1

---
 docs/TODO-backend-center-guild.md       |  2 +-
 docs/error-codes-and-retry-policy-v1.md | 75 +++++++++++++++++++++++++
 2 files changed, 76 insertions(+), 1 deletion(-)
 create mode 100644 docs/error-codes-and-retry-policy-v1.md

diff --git a/docs/TODO-backend-center-guild.md b/docs/TODO-backend-center-guild.md
index 6d72cd3..b33d788 100644
--- a/docs/TODO-backend-center-guild.md
+++ b/docs/TODO-backend-center-guild.md
@@ -65,7 +65,7 @@
 ## 3. Center ↔ Guild 协议层
 - [x] 鉴权方案定稿（node token / HMAC）
 - [x] 注册握手协议文档化
-- [ ] 错误码与重试策略统一
+- [x] 错误码与重试策略统一
 - [ ] 版本协商（`X-Fabric-Version`）
 
 ---
diff --git a/docs/error-codes-and-retry-policy-v1.md b/docs/error-codes-and-retry-policy-v1.md
new file mode 100644
index 0000000..4cad73a
--- /dev/null
+++ b/docs/error-codes-and-retry-policy-v1.md
@@ -0,0 +1,75 @@
+# 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`