# 错误代码参考

[返回主文档](../README.md) | [查看API规范](./api-common.md)

## 📋 概述
本文档列出所有版本通用的错误代码及其含义、解决方案。

## 🔢 错误代码分类

### 1xxx - 系统错误
| 错误码 | HTTP状态 | 说明 | 解决方案 |
|--------|----------|------|----------|
| `1001` | 500 | 内部服务器错误 | 联系技术支持，提供请求ID |

### 2xxx - 客户端错误
#### 认证相关 (2001-2099)
| 错误码 | HTTP状态 | 说明 | 解决方案 |
|--------|----------|------|----------|
| `2001` | 401 | 未提供认证信息 | 添加Authorization头或API Key |

#### 授权相关 (2101-2199)
| 错误码 | HTTP状态 | 说明 | 解决方案 |
|--------|----------|------|----------|
| `2101` | 403 | 权限不足 | 检查用户角色和权限 |

#### 请求验证 (2201-2299)
| 错误码 | HTTP状态 | 说明 | 解决方案 |
|--------|----------|------|----------|
| `2201` | 400 | 缺少必需参数 | 检查请求参数是否完整 |

#### 资源相关 (2301-2399)
| 错误码 | HTTP状态 | 说明 | 解决方案 |
|--------|----------|------|----------|
| `2301` | 404 | 资源不存在 | 检查资源ID是否正确 |

### 3xxx - 文件操作错误
#### 上传相关 (3001-3099)
| 错误码 | HTTP状态 | 说明 | 解决方案                                                                          |
|--------|----------|------|-------------------------------------------------------------------------------|
| `3001` | 400 | NOT_IMAGE_FILE - 文件不是有效的图片格式 | 1. 检查文件是否为支持的图片格式<br>2. 确保文件扩展名正确<br>3. 使用 `isImageFile()` 方法验证文件             |
| `3002` | 400 | FILE_TOO_LARGE - 图片文件过大 | 1. 压缩图片大小<br>2. 调整图片尺寸<br>3. 使用推荐的5MB以下图片                                     |
| `3003` | 400 | UNSUPPORTED_FORMAT - 不支持的图片格式 | 1. 转换为支持的格式（JPEG/PNG/GIF/WebP/BMP/TIFF）<br>2. 检查 `SUPPORTED_IMAGE_FORMATS` 配置 |
| `3004` | 400 | CORRUPTED_IMAGE - 图片文件已损坏 | 1. 重新下载或获取图片<br>2. 检查文件完整性<br>3. 使用其他图片编辑工具打开验证                               |
| `3005` | 400 | DIMENSIONS_TOO_SMALL - 图片尺寸过小 | 1. 使用更大尺寸的图片<br>2. 调整图片尺寸<br>3. 检查电商平台对图片尺寸的要求                                |
| `3006` | 400 | DIMENSIONS_TOO_LARGE - 图片尺寸过大 | 1. 缩小图片尺寸<br>2. 使用 `resizeImage()` 方法调整<br>3. 分批处理                            |
| `3007` | 400 | PROCESSING_FAILED - 图片处理失败 | 1. 检查图片格式兼容性<br>2. 尝试使用不同的处理参数<br>3. 查看日志获取详细错误信息                             |
| `3008` | 400 | INVALID_PATH - 文件路径不正确 | 1. 检查文件路径开头是否存在斜杠，如有请去掉<br>             |
#### 下载相关 (3101-3199)
| 错误码 | HTTP状态 | 说明 | 解决方案 |
|--------|----------|------|----------|
| `3001` | 400 | NOT_IMAGE_FILE - 文件不是有效的图片格式 | 1. 检查文件是否为支持的图片格式<br>2. 确保文件扩展名正确<br>3. 使用 `isImageFile()` 方法验证文件 |
#### 管理相关 (3201-3299)
| 错误码 | HTTP状态 | 说明 | 解决方案 |
|--------|----------|------|----------|
| `3201` | 400 | 文件重命名失败 | 新文件名可能已存在 |

### 4xxx - 图片处理错误 (1.0.4+)
| 错误码 | HTTP状态 | 说明 | 解决方案 |
|--------|----------|------|----------|
| `4001` | 400 | 不支持的图片格式 | 转换为支持的格式（JPEG/PNG/WebP） |

### 5xxx - 配置与限制错误
| 错误码 | HTTP状态 | 说明 | 解决方案 |
|--------|----------|------|----------|
| `5001` | 403 | 超出存储空间限制 | 清理文件或升级套餐 |

## 🛠️ 错误处理示例

### 客户端处理示例
```javascript
handleServerError(errorData) {
    const { code, message, data } = errorData;

    switch(code) {
        case '3001': // NOT_IMAGE_FILE
            this.showErrorToast('图片格式错误', '请上传支持的图片格式（JPEG、PNG、GIF、WebP、BMP）');
            break;

        case '3002': // FILE_TOO_LARGE
            const maxSizeMB = data?.maxSize ? data.maxSize / (1024 * 1024) : 10;
            this.showErrorToast('图片过大', `请上传小于${maxSizeMB}MB的图片`);
            break;

        case '3003': // UNSUPPORTED_FORMAT
            this.showErrorToast('格式不支持', '请转换为支持的图片格式');
            break;

        case '3004': // CORRUPTED_IMAGE
            this.showErrorToast('图片已损坏', '请重新选择或下载图片');
            break;

        case '3005': // DIMENSIONS_TOO_SMALL
            this.showErrorToast('图片尺寸过小', '请上传更大尺寸的图片（建议至少100×100像素）');
            break;

        case '3006': // DIMENSIONS_TOO_LARGE
            this.showErrorToast('图片尺寸过大', '请缩小图片尺寸（最大4096×4096像素）');
            break;

        case '3007': // PROCESSING_FAILED
            this.showErrorToast('处理失败', '图片处理失败，请稍后重试或联系技术支持');
            break;

        default:
            this.showErrorToast('上传失败', message || '未知错误');
    }

    // 记录错误日志（生产环境）
    this.logError({ code, message, data });
}

```
### 服务端错误响应示例
todo
```json
{
  "success": false,
  "code": "3001",
  "message": "文件大小超过限制",
  "errors": [
    {
      "field": "file",
      "code": "MAX_SIZE_EXCEEDED",
      "message": "文件大小不能超过10MB",
      "details": {
        "maxSize": 10485760,
        "actualSize": 15728640,
        "allowedTypes": ["jpg", "png", "gif", "pdf"]
      }
    }
  ],
  "metadata": {
    "requestId": "req_1234567890abcdef",
    "timestamp": "2025-12-03T10:30:00Z",
    "documentation": "https://docs.example.com/errors/3001",
    "support": "syfei49@163.com"
  }
}
```
## 🔄 错误恢复策略
### 自动重试策略
### 降级策略
## 📊 错误监控
### 错误统计指标
### 告警规则

## 📚 错误代码管理
### 添加新错误代码
确定类别: 根据错误类型选择分类
分配代码: 在对应范围内分配唯一代码
编写文档: 更新本文档，包含说明和解决方案
更新代码: 在代码中定义错误码常量
测试验证: 编写测试用例验证错误处理
### 错误码常量定义
```java
@Getter
public enum ImageErrorCode {

    NOT_IMAGE_FILE("3001", "文件不是有效的图片格式"),
    FILE_TOO_LARGE("3002", "图片文件过大"),
    UNSUPPORTED_FORMAT("3003", "不支持的图片格式"),
    CORRUPTED_IMAGE("3004", "图片文件已损坏"),
    DIMENSIONS_TOO_SMALL("3005", "图片尺寸过小"),
    DIMENSIONS_TOO_LARGE("3006", "图片尺寸过大"),
    PROCESSING_FAILED("3007", "图片处理失败"),
    INVALID_PATH("3008", "不支持的路径格式");

    private final String code;
    private final String description;

    ImageErrorCode(String code, String description) {
        this.code = code;
        this.description = description;
    }
}
```
## 🔗 相关文档
通用API规范

版本对比
[返回主文档](../README.md)

*错误代码版本: 1.0.0 | 最后更新: 2025-12-05*