# 表单管理 - 错误码文档

> **版本**: v1.0  
> **最后更新**: 2026-01-11  
> **维护者**: FFOA 开发团队  
> **状态**: 🚧 Draft（基于现有文档与代码实现推导）

---

## ✅ 机器读取区（必填）

### 错误码清单（最小）

| 错误码 | HTTP | 说明 | 处理建议 |
|--------|------|------|----------|
| VALIDATION_ERROR | 400 | 请求参数验证失败 | 校验请求参数 |
| UNAUTHORIZED | 401 | 未授权 | 重新登录获取 Token |
| FORBIDDEN | 403 | 无权限 | 检查权限 |
| NOT_FOUND | 404 | 资源不存在 | 校验标识 |
| REGION_REQUIRED | 400 | 缺少区域头 | 补齐 X-Region-Id |
| INVALID_REGION | 400 | 无效区域 | 使用 CN/US/ME |
| REGION_MISMATCH | 403 | 区域不一致 | 使用正确区域 |
| CROSS_REGION_FORBIDDEN | 403 | 跨区域被禁止 | 仅 admin 可操作 |
| FORM_NOT_FOUND | 404 | 表单定义不存在 | 校验定义 ID |
| VERSION_NOT_FOUND | 404 | 版本不存在 | 校验版本号 |
| SNAPSHOT_NOT_FOUND | 404 | 快照不存在 | 校验快照 ID |
| NO_ACTIVE_SNAPSHOT | 404 | 无激活版本 | 先发布表单 |
| DRAFT_ALREADY_EXISTS | 409 | 已有草稿版本 | 先处理现有草稿 |
| PENDING_ALREADY_EXISTS | 409 | 已有待审核版本 | 等待审核完成 |
| INVALID_STATUS_TRANSITION | 400 | 状态流转非法 | 按状态机操作 |
| ALREADY_PUBLISHED | 409 | 快照已发布 | 选择其他快照 |
| REVIEW_REQUIRED | 400 | 需先审核 | 先走审核流程 |
| FORM_DATA_INVALID | 422 | 表单数据验证失败 | 按字段提示修复 |
| FORM_DEFINITION_DISABLED | 403 | 表单已禁用 | 启用后再操作 |
| FORM_DEFINITION_ARCHIVED | 403 | 表单已归档 | 不允许操作 |

---

## 🧭 人类阅读区（可选）

### 示例响应（如需）

```json
{
  "success": false,
  "error": {
    "code": "REGION_REQUIRED",
    "message": "缺少区域标识"
  },
  "statusCode": 400
}
```