Skip to main content

错误代码

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

错误响应格式

所有错误响应都遵循以下格式:
{
  "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_PARAMETERSide 参数值无效
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_LISTgroup_list 中组数过多
ERROR_TOO_MANY_UIDS_IN_UID_LISTuid_list 中 UID 数量过多
ERROR_TOO_MANY_APPS_IN_APP_LISTapp_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 错误处理

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 错误处理

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_idlog_id 用于调试
  2. 检查参数:确保所有必需参数都已提供且格式正确
  3. 验证文件:确保上传的文件符合要求
  4. 检查认证:确保 API Key 有效且正确设置
  5. 联系支持:如果问题持续存在,请联系技术支持(common@tincent.me)并提供错误信息

相关链接