> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihairstyle.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 错误代码

> AI发型设计 API 错误代码详细说明

# 错误代码

本文档详细说明了 AI发型设计 API 中可能出现的错误代码及其含义。

## 错误响应格式

所有错误响应都遵循以下格式：

```json theme={null}
{
  "request_id": "请求ID",
  "log_id": "日志ID", 
  "error_code": 错误代码,
  "error_msg": "错误消息",
  "error_detail": {
    "status_code": HTTP状态码,
    "code": "错误代码",
    "code_message": "错误代码描述",
    "message": "详细错误信息"
  }
}
```

## HTTP 状态码

| 状态码 | 说明       |
| --- | -------- |
| 200 | 请求成功     |
| 400 | 请求参数错误   |
| 401 | 认证失败     |
| 422 | 请求内容无法处理 |
| 429 | 请求频率超限   |
| 500 | 服务器内部错误  |

## 常见错误代码

### 400 - 请求参数错误

| 错误代码                                       | 说明                    |
| ------------------------------------------ | --------------------- |
| `PROCESSING_FAILURE`                       | 处理失败                  |
| `ERROR_PARAMETERS`                         | 无效参数                  |
| `MISSING_PARAMETERS`                       | 缺少参数                  |
| `ERROR_INVALID_PARAMETER`                  | 无效参数                  |
| `PARAMETERS_CANNOT_EMPTY`                  | 参数不能为空                |
| `ERROR_MISSING_LIMIT_PARAMETER`            | 缺少 Limit 参数           |
| `ERROR_MISSING_TASKS_PARAMETER`            | 缺少 Tasks 参数           |
| `ERROR_MISSING_ASSURE_DIRECTION_PARAMETER` | 缺少 AssureDirection 参数 |
| `ERROR_MISSING_MIN_HEIGHT_PARAMETER`       | 缺少 MinHeight 参数       |
| `ERROR_INVALID_SIDE_PARAMETER`             | Side 参数值无效            |
| `ERROR_TOO_MANY_FILES`                     | 文件数量超限                |
| `ERROR_FACE_TRACE_LIMIT_EXCEEDED`          | 人脸或轨迹数量超限             |
| `ERROR_INVALID_URL`                        | 无效 URL                |
| `ERROR_DATABASE_LIMIT_EXCEEDED`            | 数据库限制超限               |
| `ERROR_INVALID_RESPONSE_FORMAT`            | 响应格式不正确（Accept 不支持）   |
| `ERROR_UNSUPPORTED_RESPONSE_FORMAT`        | 响应格式不正确（Format 不支持）   |
| `ERROR_TOO_MANY_GROUPS_IN_GROUP_LIST`      | group\_list 中组数过多     |
| `ERROR_TOO_MANY_UIDS_IN_UID_LIST`          | uid\_list 中 UID 数量过多  |
| `ERROR_TOO_MANY_APPS_IN_APP_LIST`          | app\_list 中应用数量过多     |
| `ERROR_CLEANING_USER_GROUP_DATA`           | 清理用户组数据               |
| `ERROR_IMAGE_STORAGE_NOT_SUPPORTED`        | 图片存储不支持               |
| `ERROR_INSUFFICIENT_RESOURCES`             | 资源不足                  |
| `ERROR_RESOURCE_IN_TRANSIT`                | 资源传输中                 |
| `ERROR_FILE_DOWNLOAD_FAILED`               | 文件下载失败                |
| `ERROR_FILE_UPLOAD_FAILED`                 | 文件上传失败                |
| `FILE_DECODING_FAILURE`                    | 文件解码失败                |
| `ERROR_FACE_BLENDING_FAILED`               | 人脸融合失败                |
| `ERROR_FACE_IMAGE_ADDITION_FAILED`         | 人脸图片添加失败              |

### 401 - 认证失败

| 错误代码           | 说明            |
| -------------- | ------------- |
| `UNAUTHORIZED` | 无效或缺少 API Key |

### 422 - 请求内容无法处理

| 错误代码                                                                           | 说明                  |
| ------------------------------------------------------------------------------ | ------------------- |
| `ERROR_NO_FACE_IN_FILE`                                                        | 文件中未检测到人脸           |
| `ERROR_FACE_NOT_PROPER_SIZE_ANGLE_LIGHTING_EXPRESSION_QUALITY_FORMAT`          | 人脸大小角度光线表情质量格式不合适   |
| `ERROR_FACE_NOT_PROPER_SIZE_ANGLE_LIGHTING_EXPRESSION_QUALITY_RESOLUTION`      | 人脸大小角度光线表情质量分辨率不合适  |
| `ERROR_FACE_NOT_PROPER_SIZE_ANGLE_LIGHTING_EXPRESSION_QUALITY_FACE_NUM`        | 人脸大小角度光线表情质量人脸数量不合适 |
| `ERROR_FACE_NOT_PROPER_SIZE_ANGLE_LIGHTING_EXPRESSION_QUALITY_FACE_RECT`       | 人脸大小角度光线表情质量人脸区域不合适 |
| `ERROR_FACE_NOT_PROPER_SIZE_ANGLE_LIGHTING_EXPRESSION_QUALITY_FACE_ANGLE`      | 人脸大小角度光线表情质量人脸角度不合适 |
| `ERROR_FACE_NOT_PROPER_SIZE_ANGLE_LIGHTING_EXPRESSION_QUALITY_FACE_PROPORTION` | 人脸大小角度光线表情质量人脸比例不合适 |
| `ERROR_FACE_NOT_PROPER_SIZE_ANGLE_LIGHTING_EXPRESSION_QUALITY_FACE_OCCLUSION`  | 人脸大小角度光线表情质量人脸遮挡不合适 |
| `ERROR_FACE_NOT_PROPER_SIZE_ANGLE_LIGHTING_EXPRESSION_QUALITY_FACE_BLUR`       | 人脸大小角度光线表情质量人脸模糊不合适 |
| `ERROR_FACE_NOT_PROPER_SIZE_ANGLE_LIGHTING_EXPRESSION_QUALITY_FACE_EXPRESSION` | 人脸大小角度光线表情质量人脸表情不合适 |
| `ERROR_FACE_NOT_PROPER_SIZE_ANGLE_LIGHTING_EXPRESSION_QUALITY_FACE_LIGHTING`   | 人脸大小角度光线表情质量人脸光线不合适 |
| `ERROR_FACE_NOT_PROPER_SIZE_ANGLE_LIGHTING_EXPRESSION_QUALITY_FACE_SIZE`       | 人脸大小角度光线表情质量人脸大小不合适 |

### 429 - 请求频率超限

| 错误代码                  | 说明     |
| --------------------- | ------ |
| `RATE_LIMIT_EXCEEDED` | 请求频率超限 |

### 500 - 服务器内部错误

| 错误代码                    | 说明      |
| ----------------------- | ------- |
| `INTERNAL_SERVER_ERROR` | 服务器内部错误 |
| `SERVICE_UNAVAILABLE`   | 服务不可用   |

## 错误处理示例

### JavaScript 错误处理

```javascript theme={null}
function handleApiError(error) {
  const { error_code, error_msg, error_detail } = error;
  
  console.error('API Error:', {
    code: error_code,
    message: error_msg,
    detail: error_detail
  });
  
  switch (error_code) {
    case 401:
      // 认证错误
      console.error('认证失败，请检查 API Key');
      break;
    case 400:
      // 参数错误
      console.error('参数错误:', error_detail.message);
      break;
    case 422:
      // 文件错误
      console.error('文件错误:', error_detail.message);
      break;
    case 429:
      // 限流错误
      console.error('请求频率超限，请稍后重试');
      break;
    case 500:
      // 服务器错误
      console.error('服务器错误，请稍后重试');
      break;
    default:
      console.error('未知错误:', error_msg);
  }
}
```

### Python 错误处理

```python theme={null}
def handle_api_error(error):
    error_code = error.get('error_code')
    error_msg = error.get('error_msg')
    error_detail = error.get('error_detail', {})
    
    print(f"API Error: {error_code} - {error_msg}")
    
    if error_code == 401:
        print("认证失败，请检查 API Key")
    elif error_code == 400:
        print(f"参数错误: {error_detail.get('message', '')}")
    elif error_code == 422:
        print(f"文件错误: {error_detail.get('message', '')}")
    elif error_code == 429:
        print("请求频率超限，请稍后重试")
    elif error_code == 500:
        print("服务器错误，请稍后重试")
    else:
        print(f"未知错误: {error_msg}")
```

## 调试建议

1. **记录错误信息**：保存 `request_id` 和 `log_id` 用于调试
2. **检查参数**：确保所有必需参数都已提供且格式正确
3. **验证文件**：确保上传的文件符合要求
4. **检查认证**：确保 API Key 有效且正确设置
5. **联系支持**：如果问题持续存在，请联系技术支持（[common@tincent.me](mailto:common@tincent.me)）并提供错误信息

## 相关链接

* [错误处理](/essentials/error-handling)
* [响应说明](/essentials/response-description)